Forms Hooks

Dynamic Forms are bundled with general hooks allowing you to change the form settings, add validation rules and trigger a custom action on submission. Those hooks are tied to forms, and act independently from Actions.

Form Arguments

The acfe/form/load fitler is used to change the form settings, right before it is rendered on the page. Note that fields inputs cannot be retrieved using get_field() here, as the form hasn’t been submitted yet. Usage example:

/*
 * Form Load
 * 
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 */
 
filter('acfe/form/load',              $form, $post_id);
filter('acfe/form/load/form=my-form', $form, $post_id);
add_filter('acfe/form/load/form=my-form', 'my_form_load', 10, 2);
function my_form_load($form, $post_id){
    
    // Change form success message dynamically
    $form['updated_message'] = 'New success message!';
    
    // Hide the form
    // return false;
    
    // Return
    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:

<p>Success Message</p>

<!-- acfe/form/render/before_form -->

<form class="acfe-form">

    <!-- acfe/form/render/before_fields -->

    <div class="acf-fields">
    
        <div class="acf-field">
            <div class="acf-label">Field</div>
            <div class="acf-input">
                <input type="text" />
            </div>
        </div>
        
    </div>
    
    <div class="acf-form-submit">
        <input type="submit" class="acf-button" value="Submit" />                
    </div>
    
    <!-- acfe/form/render/after_fields -->

</form>

<!-- acfe/form/render/after_form -->

Before Form Render

/*
 * Form Render: Before Form
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render/before_form',                $form);
action('acfe/form/render/before_form/id=123',         $form);
action('acfe/form/render/before_form/name=my-form',   $form);

Before Fields Render

/*
 * Form Render: Before Fields
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render/before_fields',              $form);
action('acfe/form/render/before_fields/id=123',       $form);
action('acfe/form/render/before_fields/name=my-form', $form);

After Fields Render

/*
 * Form Render: After Fields
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render/after_fields',               $form);
action('acfe/form/render/after_fields/id=123',        $form);
action('acfe/form/render/after_fields/name=my-form',  $form);

After Form Render

/*
 * Form Render: After Form
 *
 * @array  $form  Form arguments
 */
 
action('acfe/form/render/after_form',                 $form);
action('acfe/form/render/after_form/id=123',          $form);
action('acfe/form/render/after_form/name=my-form',    $form);

Form Validation

The acfe/form/validation action is used to add rules during the ajax form validation process, before form submission.

Unlike the acf/validate_value hook which validate each fields values individually, acfe/form/validation will validate the whole form. It can be used to check one field against an another.

The acfe_add_validation_error() function should be used to return an error. It is possible to return a general error by omitting to reference a field’s name. Example: acfe_add_validation_error('', 'General error message'). Usage example:

/*
 * Form Validation
 * 
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 */
 
action('acfe/form/validation',              $form, $post_id);
action('acfe/form/validation/form=my-form', $form, $post_id);
add_action('acfe/form/validation/form=my-form', 'my_form_validation', 10, 2);
function my_form_validation($form, $post_id){
    
    // 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');
        
    }
    
}

Form Submission

The acfe/form/submit action is used to trigger a custom script on form submission, after its validation. Usage example:

/*
 * Form Submit
 * 
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 */
 
action('acfe/form/submit',              $form, $post_id);
action('acfe/form/submit/form=my-form', $form, $post_id);
add_action('acfe/form/submit/form=my-form', 'my_form_submit', 10, 2);
function my_form_submit($form, $post_id){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Do something...
    
    }
    
}

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  $value    Field value (already formatted by ACF)
 * @mixed  $_value   Unformatted field value
 * @int    $post_id  Post ID (where the form is displayed)
 * @array  $field    Field configuration
 */
 
filter('acfe/form/format_value',                         $value, $_value, $post_id, $field);
filter('acfe/form/format_value/type=text',               $value, $_value, $post_id, $field);
filter('acfe/form/format_value/key=field_609bc6213c51b', $value, $_value, $post_id, $field);
filter('acfe/form/format_value/name=my_field',           $value, $_value, $post_id, $field);
add_filter('acfe/form/format_value/name=my_field', 'my_form_format_value', 10, 2);
function my_form_format_value($value, $_value, $post_id, $field){
    
    // Apply change
    $value = ucfirst($value);
    
    // Return value
    return $value;
    
}

JavaScript Success

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

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

/*
 * JavaScript Success
 */
 
action('acfe/form/submit/success');
action('acfe/form/submit/success/id=192');
action('acfe/form/submit/success/name=my-form');
acf.addAction('acfe/form/submit/success/name=my-form', function(){

    // do_something();

});