Hooks FREE

Docs Modules Forms Hooks

#Form Arguments

The acfe/form/load_form filter is used to change the form settings, right before it is rendered on the page. See Settings Cheatsheet for more details.

Usage example:

/**
 * Form Load
 * 
 * @array $form  Form array settings
 *
 * @return array|false
 */
 
filter('acfe/form/load_form',              $form);
filter('acfe/form/load_form/form=my-form', $form);
add_filter('acfe/form/load_form/form=my-form', 'my_form_load');
function my_form_load($form){
    
    // change form success message dynamically
    $form['success']['message'] = 'New success message!';

    // preload repeater values
    $form['map']['field_621a65c15521d']['value'] = array(
        array(
            'field_621a65cc5521e' => 'Row 1'
        ),
        array(
            'field_621a65cc5521e' => 'Row 2'
        ),
    );

    // change field label
    $form['map']['field_621a65c15521d']['label'] = 'New label';

    // add field instruction
    $form['map']['field_621a65c15521d']['instructions'] = 'New instructions';
    
    // hide the form
    // return false;
    
    // return normally
    return $form;
    
}

#Form Render

Forms have multiple hooks allowing developers to display custom code on form render.

Here is a visual representation of the hooks placement on the page:

<!-- acfe/form/render_success (priority:9) -->
<div id="message" class="updated">
    <p>Success Message</p>
</div>
<!-- acfe/form/render_success (priority:10) -->


<!-- acfe/form/render_before_form (priority:9) -->
<form class="acfe-form">
<!-- acfe/form/render_before_form (priority:10) -->


    <!-- acfe/form/render_before_fields (priority:9) -->
    <div class="acf-fields">
    <!-- acfe/form/render_before_fields (priority:10) -->


        <!-- acfe/form/render_fields (priority:9) -->
        <div class="acf-field">...</div>
        <div class="acf-field">...</div>
        <div class="acf-field">...</div>
        <!-- acfe/form/render_fields (priority:10) -->
    

    <!-- acfe/form/render_after_fields (priority:9) -->
    </div>
    <!-- acfe/form/render_after_fields (priority:10) -->


    <!-- acfe/form/render_submit (priority:9) -->
    <div class="acf-form-submit">
        <button>Submit</button>
    <div>
    <!-- acfe/form/render_submit (priority:10) -->


<!-- acfe/form/render_after_form (priority:9) -->
</form>
<!-- acfe/form/render_after_form (priority:10) -->
/**
 * Form Render: Success
 *
 * @array  $form  Form arguments
 */

action('acfe/form/render_success',                    $form);
action('acfe/form/render_success/form=my-form',       $form);
/**
 * Form Render: Before Form
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render_before_form',                $form);
action('acfe/form/render_before_form/form=my-form',   $form);
/**
 * Form Render: Before Fields
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render_before_fields',              $form);
action('acfe/form/render_before_fields/form=my-form', $form);
/**
 * Form Render: After Fields
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render_after_fields',               $form);
action('acfe/form/render_after_fields/form=my-form',  $form);
/**
 * Form Render: After Form
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render_after_form',                 $form);
action('acfe/form/render_after_form/form=my-form',    $form);

#Form Validation

The acfe/form/validate_form action can be used to validate all fields at once and check one field value against another one.

In this hook, the helper function acfe_add_validation_error() should be used to throw an error either for a specific field, or a general error (see documentation).

/**
 * Form Validation
 * 
 * @array $form  Form array settings
 */
 
action('acfe/form/validate_form',              $form);
action('acfe/form/validate_form/form=my-form', $form);
add_action('acfe/form/validate_form/form=my-form', 'my_form_validation');
function my_form_validation($form){
    
    // get current post id
    // where the form is displayed (in case you need it)
    $post_id = $form['post_id'];
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        
        // add field validation error
        acfe_add_validation_error('my_field', 'The value Company is not allowed');

        // or, add global validation error
        // acfe_add_validation_error('', 'An error occured');
        
    }
    
}
You can use the acfe/form/validate_valuehook to validate fields individually on the front-end. This filter is similar to the native acf/validate_value filter, but applied to front-end forms fields only.

This hook works the same as the native ACF filter and comes with an additional $form argument to get the form data related to the field.

/**
 * Field Validation
 * 
 * @bool/string $valid The valid state (true/false or error message)
 * @mixed       $value The field value
 * @array       $field The field array settings
 * @string      $input The field input name
 * @array       $form  Form array settings
 */
 
filter('acfe/form/validate_value',                         $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/form=my-form',            $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/type=textarea',           $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/name=my_field',           $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/key=field_67290208037b8', $valid, $value, $field, $input, $form);
add_filter('acfe/form/validate_value/name=my_field', 'my_form_field_validation', 10, 5);
function my_form_field_validation($valid, $value, $field, $input, $form){

    // already invalid
    if(!$valid){
        return $valid;
    }
    
    // check field value
    if($value === 'Company'){
        
        // return a specific error message
        return 'The value Company is not allowed';

        // or, return a generic validation error message
        // return false;
        
    }
    
    // return normally
    return $valid;
    
}
By default, each ACF fields are validated individually against their respective choices defined in the field settings. This enforced validation make sure the submitted value is allowed before being processed.

The filter responsible to control this behavior is named acfe/form/pre_validate_value and return true by default.

It is possible to disable it by returning false. Note that if you decide to do so, it is advised to add your own validation to make sure the submitted value is allowed.

/**
 * Enforced Field Validation
 * 
 * @bool   $validate Enable the enforced field validation
 * @array  $field    The field array settings
 * @array  $form     Form array settings
 */
 
filter('acfe/form/pre_validate_value',                         $validate, $field, $form);
filter('acfe/form/pre_validate_value/form=my-form',            $validate, $field, $form);
filter('acfe/form/pre_validate_value/type=textarea',           $validate, $field, $form);
filter('acfe/form/pre_validate_value/name=my_field',           $validate, $field, $form);
filter('acfe/form/pre_validate_value/key=field_67290208037b8', $validate, $field, $form);
// disable enforced front-end validation for "my_field"
add_filter('acfe/form/pre_validate_value/name=my_field', '__return_false');

// disable enforced front-end validation for all "checkbox" fields
add_filter('acfe/form/pre_validate_value/type=checkbox', '__return_false');

// disable enforced front-end validation for all fields from "my-form"
add_filter('acfe/form/pre_validate_value/form=my-form', '__return_false');

#Form Submission

The acfe/form/submit_form action is used to trigger a custom script on form submission, after its validation and after all actions have been submitted. Usage example:

/**
 * Form Submit
 * 
 * @array  $form  Form array settings
 */
 
action('acfe/form/submit_form',              $form);
action('acfe/form/submit_form/form=my-form', $form);
add_action('acfe/form/submit_form/form=my-form', 'my_form_submit');
function my_form_submit($form){

    // 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'){
        // do something
    }
    
}

#Form Success

You can use the acfe/form/render_success hook to display advanced success message with dynamic data. Usage example:

/**
 * Render Success
 * 
 * @array  $form  Form settings
 */
 
action('acfe/form/render_success',              $form);
action('acfe/form/render_success/form=my-form', $form);
add_action('acfe/form/render_success/form=my-form', 'my_form_render_success');
function my_form_render_success($form){
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        echo 'The form has been successfully submitted!';
    }
    
}
The acfe/form/submit_success hook is executed in the headers of the page, when the form has been successfully submitted, and all actions are done. It’s the ideal place to perform a redirection or setup variables for your page.

/**
 * Submit Success
 *
 * @array  $form  Form settings
 */

action('acfe/form/submit_success',              $form);
action('acfe/form/submit_success/form=my-form', $form);
add_action('acfe/form/submit_success/form=my-form', 'my_form_submit_success');
function my_form_submit_success($form){
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        wp_redirect(home_url('thank-you'));
        exit;
    }
    
}

#Format Values

It is possible to format the return value of the {field:my_field} and {fields} templates tags using the acfe/form/format_value filter. Usage example:

/**
 * Format Value
 * 
 * @mixed  $formatted    Field value (already formatted by ACF)
 * @mixed  $unformatted  Unformatted field value
 * @int    $post_id      Post ID (where the form is displayed)
 * @array  $field        Field settings array
 */
 
filter('acfe/form/format_value',                         $formatted, $unformatted, $post_id, $field);
filter('acfe/form/format_value/type=text',               $formatted, $unformatted, $post_id, $field);
filter('acfe/form/format_value/key=field_609bc6213c51b', $formatted, $unformatted, $post_id, $field);
filter('acfe/form/format_value/name=my_field',           $formatted, $unformatted, $post_id, $field);
add_filter('acfe/form/format_value/name=my_field', 'my_form_format_value', 10, 4);
function my_form_format_value($formatted, $unformatted, $post_id, $field){
    
    // apply change
    $value = ucfirst($value);
    
    // return value
    return $value;
    
}

#JavaScript Hooks

It is recommended to use the acf/input/admin_enqueue_scripts hook to enqueue a custom ACF JS file. See documentation.

/**
 * Validation Begin: JS hook
 * 
 * @jQuery  $el       The form jquery element
 * @object  validator The validator instance
 * @object  form      The form instance
 */
 
action('acfe/form/validation_begin',              $el, validator, form);
action('acfe/form/validation_begin/form=my-form', $el, validator, form);
acf.addAction('acfe/form/validation_begin/form=my-form', function($el, validator, form){

    // console.log($el, validator, form);

});
/**
 * Validation Failure: JS hook
 * 
 * @jQuery  $el       The form jquery element
 * @object  validator The validator instance
 * @object  form      The form instance
 */
 
action('acfe/form/validation_failure',              $el, validator, form);
action('acfe/form/validation_failure/form=my-form', $el, validator, form);
acf.addAction('acfe/form/validation_failure/form=my-form', function($el, validator, form){

    // console.log($el, validator, form);

});
/**
 * Validation Success: JS hook
 * 
 * @jQuery  $el       The form jquery element
 * @object  validator The validator instance
 * @object  form      The form instance
 */
 
action('acfe/form/validation_success',              $el, validator, form);
action('acfe/form/validation_success/form=my-form', $el, validator, form);
acf.addAction('acfe/form/validation_success/form=my-form', function($el, validator, form){

    // console.log($el, validator, form);

});
/**
 * Validation Complete: JS hook
 * 
 * @object  data      The errors data
 * @jQuery  $el       The form jquery element
 * @object  validator The validator instance
 * @object  form      The form instance
 */
 
filter('acfe/form/validation_complete',              data, $el, validator, form);
filter('acfe/form/validation_complete/form=my-form', data, $el, validator, form);
acf.addFilter('acfe/form/validation_complete/form=my-form', function(data, $el, validator, form){

    // console.log(data, $el, validator, form);

    return data;

});
/**
 * Submit: JS hook
 * 
 * @jQuery  $el       The form jquery element
 * @object  validator The validator instance
 * @object  form      The form instance
 */
 
action('acfe/form/submit',              $el, validator, form);
action('acfe/form/submit/form=my-form', $el, validator, form);
acf.addAction('acfe/form/submit/form=my-form', function($el, validator, form){

    // console.log($el, validator, form);

});
The following Javascript hook is triggered on the form success page and can be used to perform a custom action.

/**
 * Submit Success: JS hook
 * 
 * @jQuery  $el  The form jquery element
 * @object  form The form instance
 * @object  data The form data
 */
 
action('acfe/form/submit_success',              $el, form, data);
action('acfe/form/submit_success/form=my-form', $el, form, data);
acf.addAction('acfe/form/submit_success/form=my-form', function($el, form, data){

    // console.log($el, form, data);

});

Index
Form Arguments
Form Render
Cheatsheet
Success
Before Form
Before Fields
After Fields
After Form
Form Validation
Global Validation
Field Validation
Enforced Field Validation
Form Submission
Form Success
Render Success
Submit Success
Format Values
JavaScript Hooks
Valid. Begin
Valid. Failure
Valid. Success
Valid. Complete
Submit
Success