The acfe/form/load_form filter is used to change the form settings, right before it is rendered on the page. See Settings Cheatsheet for more details.
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.
<!-- 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) -->/**
* Form Render: Success
*
* @array $form Form arguments
*/
action('acfe/form/render_success', $form);
action('acfe/form/render_success/form=my-form', $form);/**
* 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);/**
* 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);/**
* 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);/**
* 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);acfe/form/validate_form action can be used to validate all fields at once, as it allows to check one field value against another one.Use the helper function acfe_add_validation_error() to return an error. Note that it is possible to return a general error by omitting to reference a field’s name.
/**
* 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 field validation error
acfe_add_validation_error('my_field', 'The value Company is not allowed');
// add global validation error
acfe_add_validation_error('', 'An error occured');
}
}acf/validate_value filter, you can use the hook acfe/form/validate_value to validate each fields individually on the front-end specifically.This hook works the same as the native ACF filter, and also comes with an additional $form argument to get more context.
/**
* Field Validation
*
* @bool/string $valid The valid state (true/false or error message)
* @mixed $value The field value
* @array $field The field array settings
* @string $input The field input name
* @array $form Form array settings
*/
filter('acfe/form/validate_value', $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/form=my-form', $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/type=textarea', $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/name=my-field', $valid, $value, $field, $input, $form);
filter('acfe/form/validate_value/key=field_67290208037b8', $valid, $value, $field, $input, $form);add_filter('acfe/form/validate_value/name=my-field', 'my_form_field_validation', 10, 5);
function my_form_field_validation($valid, $value, $field, $input, $form){
// already invalid
if(!$valid){
return $valid;
}
// check field value
if($value === 'Company'){
// return a specific error message
return 'The value Company is not allowed';
// return a generic validation error message
// return false;
}
// return normally
return $valid;
}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
}
}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!';
}
}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;
}
}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;
}It is recommended to use the acf/input/admin_enqueue_scripts hook to enqueue a custom ACF JS file. See documentation.
/**
* Validation Begin: JS hook
*
* @jQuery $el The form jquery element
* @object validator The validator instance
* @object form The form instance
*/
action('acfe/form/validation_begin', $el, validator, form);
action('acfe/form/validation_begin/form=my-form', $el, validator, form);acf.addAction('acfe/form/validation_begin/form=my-form', function($el, validator, form){
// console.log($el, validator, form);
});/**
* Validation Failure: JS hook
*
* @jQuery $el The form jquery element
* @object validator The validator instance
* @object form The form instance
*/
action('acfe/form/validation_failure', $el, validator, form);
action('acfe/form/validation_failure/form=my-form', $el, validator, form);acf.addAction('acfe/form/validation_failure/form=my-form', function($el, validator, form){
// console.log($el, validator, form);
});/**
* Validation Success: JS hook
*
* @jQuery $el The form jquery element
* @object validator The validator instance
* @object form The form instance
*/
action('acfe/form/validation_success', $el, validator, form);
action('acfe/form/validation_success/form=my-form', $el, validator, form);acf.addAction('acfe/form/validation_success/form=my-form', function($el, validator, form){
// console.log($el, validator, form);
});/**
* Validation Complete: JS hook
*
* @object data The errors data
* @jQuery $el The form jquery element
* @object validator The validator instance
* @object form The form instance
*/
filter('acfe/form/validation_complete', data, $el, validator, form);
filter('acfe/form/validation_complete/form=my-form', data, $el, validator, form);acf.addFilter('acfe/form/validation_complete/form=my-form', function(data, $el, validator, form){
// console.log(data, $el, validator, form);
return data;
});/**
* Submit: JS hook
*
* @jQuery $el The form jquery element
* @object validator The validator instance
* @object form The form instance
*/
action('acfe/form/submit', $el, validator, form);
action('acfe/form/submit/form=my-form', $el, validator, form);acf.addAction('acfe/form/submit/form=my-form', function($el, validator, form){
// console.log($el, validator, form);
});/**
* Submit Success: JS hook
*
* @jQuery $el The form jquery element
* @object form The form instance
* @object data The form data
*/
action('acfe/form/submit_success', $el, form, data);
action('acfe/form/submit_success/form=my-form', $el, form, data);acf.addAction('acfe/form/submit_success/form=my-form', function($el, form, data){
// console.log($el, form, data);
});