Term Action

The Term Action is a template to create or update a term on form submission.

Term Settings

Setting nameDescription
Action typeCreate or update a term
Action nameAlias name allowing to use targeted hook
TargetThe term to update
SourceThe term to retrieve fields from
Load valuesFill inputs with values
NameThe term name
SlugThe term slug
TaxonomyThe term taxonomy
ParentThe term parent
DescriptionThe term description
Save ACF fieldsChoose which ACF fields should be saved to this term
Load ACF fieldsChoose which ACF fields should have their values loaded

Validation

By default, there is no validation for this Action. You can use the acf/validate_value hook to validate each fields individually.

To validate the whole form, you can use the acfe/form/validation/term hook and throw errors with the acfe_add_validation_error() function. Usage example:

/*
 * Term Validation
 * 
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 * @string  $action   Action name
 */
 
action('acfe/form/validation/term',                $form, $post_id, $action);
action('acfe/form/validation/term/form=my-form',   $form, $post_id, $action);
action('acfe/form/validation/term/action=my-term', $form, $post_id, $action);
add_action('acfe/form/validation/term/form=my-form', 'my_form_validation', 10, 3);
function my_form_validation($form, $post_id, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
        
        // Add validation error
        acfe_add_validation_error('my_field', 'The value Company is not allowed');
        
    }
    
}

Prepare

The preparation phase is triggered after the form validation and before its submission. The acfe/form/prepare/term hook allows you to stop the Action early if necessary.

It is also the best place to add some logic or create new query vars that could be used within the Action UI. Returning false will stop the Action and go to the next one. Usage example:

/*
 * Term Prepare
 * 
 * @bool    $prepare  True/false
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 * @string  $action   Action name
 */
 
filter('acfe/form/prepare/term',                $prepare, $form, $post_id, $action);
filter('acfe/form/prepare/term/form=my-form',   $prepare, $form, $post_id, $action);
filter('acfe/form/prepare/term/action=my-post', $prepare, $form, $post_id, $action);
add_filter('acfe/form/prepare/term/form=my-form', 'my_form_prepare', 10, 4);
function my_form_prepare($prepare, $form, $post_id, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    // Create custom message
    $message = 'This is a custom message. Field value: ' . $my_field;
    
    // Retrive the message using {query_var:term_message} in the Term Action UI
    set_query_var('term_message', $message);
    
    // Do not create/update term if user isn't logged in
    if(!is_user_logged_in()){
        
        $prepare = false;
        
    }
    
    // return
    return $prepare;
    
}

Values Source

Alter the term ID where meta values are loaded from. Usage example:

/*
 * Term Values Source
 * 
 * @int     $term_id  Term ID Source
 * @array   $form     Form settings
 * @string  $action   Action name
 */

filter('acfe/form/load/term_id',                $term_id, $form, $action);
filter('acfe/form/load/term_id/form=my-form',   $term_id, $form, $action);
filter('acfe/form/load/term_id/action=my-term', $term_id, $form, $action);
add_filter('acfe/form/load/term_id/form=my-form', 'my_form_term_source', 10, 3);
function my_form_term_source($term_id, $form, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Force to load values from the term ID 15
        $term_id = 15;
    
    }
    
    // return
    return $term_id;
    
}

Term Arguments

Alter the term arguments before database insert/update. Usage example:

/*
 * Term Arguments
 * 
 * @array   $args    Generated term arguments
 * @string  $type    Action type: 'insert_term' or 'update_term'
 * @array   $form    Form settings
 * @string  $action  Action name
 */

filter('acfe/form/submit/term_args',                $args, $type, $form, $action);
filter('acfe/form/submit/term_args/form=my-form',   $args, $type, $form, $action);
filter('acfe/form/submit/term_args/action=my-term', $args, $type, $form, $action);
add_filter('acfe/form/submit/term_args/form=my-form', 'my_form_term_args', 10, 4);
function my_form_term_args($args, $type, $form, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Change term description
        $args['description'] = 'My description';
    
    }
    
    // Stop term creation/update
    // return false;
    
    // return
    return $args;
    
}

Submit

Trigger a custom action after the term was created/updated using the acfe/form/submit/term hook. Usage example:

/*
 * Term Submit
 * 
 * @int     $term_id  Created/Updated term ID
 * @string  $type     Action type: 'insert_term' or 'update_term'
 * @array   $args     Generated term arguments
 * @array   $form     Form settings
 * @string  $action   Action name
 */
 
action('acfe/form/submit/term',                $term_id, $type, $args, $form, $action);
action('acfe/form/submit/term/form=my-form',   $term_id, $type, $args, $form, $action);
action('acfe/form/submit/term/action=my-term', $term_id, $type, $args, $form, $action);
add_action('acfe/form/submit/term/form=my-form', 'my_form_submit', 10, 5);
function my_form_submit($term_id, $type, $args, $form, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Do something...
    
    }
    
}

Query Var

After the action completion, a query var with the term arguments is automatically genereated. This query var is useful to retrieve the action information in the UI using {query_var:my-term:term_id} or in PHP using get_query_var('my-term')['term_id'].

If the action is named, the query var will simply use its name: my-term-action. If there is no action name, it will be named my-form-term . If there are multiple term actions without names, the second term query var will be called my-form-term-2 and so on.

The acfe/form/query_var/term hook allows you to change the data that is returned. Usage example:

/*
 * Term Query var
 * 
 * @array   $data     Term information
 * @array   $term_id  Created/Updated term ID
 * @string  $type     Action type: 'insert_term' or 'update_term'
 * @array   $args     Term arguments
 * @array   $form     Form settings
 * @string  $action   Action name
 */
 
filter('acfe/form/query_var/term',                $data, $term_id, $type, $args, $form, $action);
filter('acfe/form/query_var/term/form=my-form',   $data, $term_id, $type, $args, $form, $action);
filter('acfe/form/query_var/term/action=my-term', $data, $term_id, $type, $args, $form, $action);
add_filter('acfe/form/query_var/term/form=my-form', 'my_form_query_var', 10, 6);
function my_form_query_var($data, $term_id, $type, $args, $form, $action){
    
    /*
     * $data
     *
     * Array
     * (
     * [term_id] => 72
     * [name] => My Term
     * [slug] => my-term
     * [term_group] => 0
     * [term_taxonomy_id] => 72
     * [taxonomy] => category
     * [description] => My description
     * [parent] => 0
     * [count] => 0
     * [filter] => raw
     * [permalink] => /category/my-term
     * [admin_url] => /wp-admin/term.php?tag_ID=72&taxonomy=category
     * )
     */
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
        
        // Set a custom key
        $data['custom_key'] = 'custom_value';
        
    }
    
    // return
    return $data;
    
}