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.
The acfe/form/load_form filter 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 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;
}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);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');
}
}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
}
}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/success_form/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
This 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;
}
}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;
}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();
});