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, $post_id);
filter('acfe/form/load_form/form=my-form', $form, $post_id);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:
<p>Success Message</p>
<!-- acfe/form/render_before_form -->
<form class="acfe-form">
<div class="acf-fields">
<!-- acfe/form/render_before_fields -->
<!-- acfe/form/render_fields -->
<div class="acf-field">
<div class="acf-label">Field</div>
<div class="acf-input">
<input type="text" />
</div>
</div>
<!-- acfe/form/render_after_fields -->
</div>
</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/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/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/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 array settings
*/
action('acfe/form/validate_form', $form);
action('acfe/form/validate_form/form=my-form', $form);add_action('acfe/form/validation/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
}
}It is possible to use the acfe/form/success_form hook to display advanced success message with dynamic data. Note that you’ll have to leave the “Success Message” setting in the Form UI empty, to avoid having multiple messages.
Additionally, please note that if you want to use form field input values using get_field(), you’ll have to make sure you don’t have any “Redirect Action”. Usage example:
/**
* Form Success
*
* @array $form Form settings
*/
action('acfe/form/success_form', $form);
action('acfe/form/success_form/name=my-form', $form);add_action('acfe/form/success_form/name=my-form', 'my_form_success');
function my_form_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!';
}
}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.
/*
* 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();
});