Term Action FREE

#Term Action

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

#Term Settings

#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)
    // retrieve the 'post_title' specifically
    $post_title = acfe_get_form_action('post.post_title');
    
    // check the post title
    // and change term description
    if($post_title === 'My Post'){
        $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)
    // retrieve the 'post_title' specifically
    $post_title = acfe_get_form_action('post.post_title');
    
    // check the post title
    if($post_title === 'My Post'){
        // do something
    }

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

#Output

The Action Output allows retrieve the action data in a future action within the Form UI using a Template Tag, or a PHP hook using a function.

For example, the Template Tag {action:term:name} will output the latest Term “Name”. The equivalent in PHP is acfe_get_form_action('term.name').

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;
    
}