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 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 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!';
// Preload repeater value
$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
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">
<!-- 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);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');
}
}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...
}
}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;
}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();
});