Action: Term

Features Modules Forms Action: Term

Term Action

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

Dynamic Form

Add actions on form submission

Click the "Add action" button below to start creating your layout
0 Custom action
Documentation
Action

Set a unique action slug.

0 Email action
0 Option action
Documentation
Action

(Optional) Target this action using hooks.

Save
Load

Fill inputs with values

0 Post action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

0 Redirect action
Documentation
Action

(Optional) Target this action using hooks.

The URL to redirect to. See "Cheatsheet" tab for all available template tags.

0 Term action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

0 User action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

1 Term action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

Add action

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/validate_term hook and throw errors with the acfe_add_validation_error() function. Usage example:

/**
 * Term Action: Validation
 * 
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 */
 
action('acfe/form/validate_term',                $form, $action);
action('acfe/form/validate_term/form=my-form',   $form, $action);
action('acfe/form/validate_term/action=my-term', $form, $action);
add_action('acfe/form/validate_term/form=my-form', 'my_term_validation', 10, 2);
function my_term_validation($form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    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. Returning false will stop the Action and go to the next one. Usage example:

/**
 * Term Action: Prepare
 * 
 * @array  $action  Action settings array
 * @array  $form    Form settings array
 *
 * @return array|false
 */
 
filter('acfe/form/prepare_term',                $action, $form);
filter('acfe/form/prepare_term/form=my-form',   $action, $form);
filter('acfe/form/prepare_term/action=my-post', $action, $form);
add_filter('acfe/form/prepare/term/form=my-form', 'my_term_prepare', 10, 2);
function my_term_prepare($action, $form){
    
    // if user isn't logged in
    // do not create/update the term
    if(!is_user_logged_in()){
        return false;
    }
    
    // return normally
    return $action;
    
}

Values Source

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

/**
 * Term Action: Values Source
 * 
 * @int    $term_id  Term ID source
 * @array  $form     Form settings array
 * @array  $action   Action settings array
 *
 * @return int
 */

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_term_load_id', 10, 3);
function my_term_load_id($term_id, $form, $action){
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    // and force to load values from the term id 15
    if($my_field === 'Company'){
        $post_id = 15;
    }
    
    // return normally
    return $post_id;
    
}

Term Arguments

Change the term arguments before database insert/update. Those arguments are later passed to wp_insert_term() or wp_update_term() (See documentation). Usage example:

/**
 * Term Action: Arguments
 * 
 * @array  $args    Term arguments, later passed to wp_insert_term()
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 * 
 * @return array|false
 */

filter('acfe/form/submit_term_args',                $args, $form, $action);
filter('acfe/form/submit_term_args/form=my-form',   $args, $form, $action);
filter('acfe/form/submit_term_args/action=my-term', $args, $form, $action);
add_filter('acfe/form/submit_term_args/form=my-form', 'my_term_submit_args', 10, 3);
function my_term_submit_args($args, $form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];

    // get the action type
    // either 'insert_term' or 'update_term'
    $action_type = $action['type'];
    
    // get the form input value
    $my_field = get_field('my_field');
    
    // check field value
    // and change the term description
    if($my_field === 'Company'){
        $args['description'] = 'New description';
    }

    // get previous post action output (if any)
    $post_action = acfe_form_get_action('post');

    // check previous post action exists
    if(!empty($post_action)){
    
        // check the post title of the created post
        // and change term description
        if($post_action['post_title'] === 'Post Title'){
            $args['description'] = 'New description';
        }

    }

    // do not create/update term
    // return false;
    
    // return normally
    return $args;
    
}

Submit

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

/**
 * Term Action: Submit
 * 
 * @int    $term_id  Created/Updated term ID
 * @array  $args     Term arguments
 * @array  $form     Form settings array
 * @array  $action   Action settings array
 */
 
action('acfe/form/submit_term',                $term_id, $args, $form, $action);
action('acfe/form/submit_term/form=my-form',   $term_id, $args, $form, $action);
action('acfe/form/submit_term/action=my-term', $term_id, $args, $form, $action);
add_action('acfe/form/submit_term/form=my-form', 'my_term_submit', 10, 4);
function my_term_submit($term_id, $args, $form, $action){
    
    // get current post id
    // where the form is displayed
    $current_post_id = $form['post_id'];

    // get the action type
    // either 'insert_term' or 'update_term'
    $action_type = $action['type'];
    
    // get the form input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        // do something
    }

    // get previous post action output (if any)
    $post_action = acfe_form_get_action('post');

    // check previous post action exists
    if(!empty($post_action)){
    
        // check the post title of the created post
        if($post_action['post_title'] === 'Post Title'){
            // do something
        }

    }

    // manually update a field on the created/updated term
    update_field('my_field', 'my_value', "term_{$term_id}");
    
}

Output

The Action Output let developers retrieve the action data in a future action within the Form UI or a PHP hook. For example, the Template Tag {action:term:name} will output the latest Term Action “Name” setting.

If the action is named, the Template Tag will use it. Ie: {action:my-term:name}. The equivalent function in PHP is acfe_form_get_action('term').

It is possible to change the output of a Term Action using the acfe/form/submit_term_output filter. Usage example:

/**
 * Term Action: Output
 * 
 * @array  $output   Output information
 * @array  $args     Term arguments
 * @array  $form     Form settings array
 * @array  $action   Action settings array
 * 
 * @return array
 */
 
filter('acfe/form/submit_term_output',                $output, $args, $form, $action);
filter('acfe/form/submit_term_output/form=my-form',   $output, $args, $form, $action);
filter('acfe/form/submit_term_output/action=my-term', $output, $args, $form, $action);
add_filter('acfe/form/submit_term_output/form=my-form', 'my_term_output', 10, 4);
function my_term_output($output, $args, $form, $action){
    
    /**
     * $output = 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');
    
    // check field value
    if($my_field === 'Company'){
    
        // set a custom key/value pair in the output
        $output['custom_key'] = 'custom_value';
    
    }
    
    // return normally
    return $output;
    
}
Index
Term Action
Term Settings
Validation
Prepare
Values Source
Term Arguments
Submit
Output
Functions
acfe_add_validation_error()
Hooks
acfe/form/validate_term
acfe/form/prepare_term
acfe/form/load_term_id
acfe/form/submit_term_args
acfe/form/submit_term
acfe/form/submit_term_output
Screenshots
Field Groups Field Settings Fields Modules
Block Types PRO Classic Editor PRO Developer Mode PRO Forms PRO
Integration PRO Cheatsheet Helpers Hooks Action: Custom Action: E-mail Action: Option PRO Action: Post Action: Redirect Action: Term Action: User
Options Pages PRO Performance Mode PRO Post Types PRO Rewrite Rules PRO Scripts PRO Settings UI PRO Taxonomies PRO Templates PRO
WordPress Hooks & Helpers