Form Arguments

The acfe/form/load_form filter is used to change the form settings, right before it is rendered on the page. 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) -->

Success Render

/**
 * Form Render: Success
 *
 * @array  $form  Form arguments
 */

action('acfe/form/render_success',                    $form);
action('acfe/form/render_success/form=my-form',       $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/form=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/form=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/form=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/form=my-form',    $form);

Form Validation

The acfe/form/validate_form 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/validate_form 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 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
    $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');
        
    }
    
}

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

Render 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!';
    }
    
}

Submit Success

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 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.

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

    // do_something();

});