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 use the acfe/form/success 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);
action('acfe/form/success/name=my-form', $form);add_action('acfe/form/success/name=my-form', 'my_form_success');
function my_form_success($form){
// Get field input value
$my_field = get_field('my_field');
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 $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();
});