First you need to create a Field Group that will contain the form’s fields. Then create a new Form from the ACF > Forms menu and assign that Field Group to the form. Once saved, the form will now map the Fields from the Field Group. This means those fields will be usable directly from the UI.
Out-of-the-box, the form will do nothing on submission. You can either add one or multiple actions in the UI to define what you want to do with the form, or simply use Global Forms Hooks to manage everything in PHP.
Note that you don’t need to use acf_form_head() in your front-end template anymore. ACF Extended automatically handle that part.
You can display the form using the acfe_form() function. Usage example:
<?php get_header(); ?>
<?php
// Using Form Name
acfe_form('my-form');
// Using Form ID
acfe_form(120);
// Using Form Array
acfe_form(array(
'name' => 'my-form'
));
?>
<?php get_footer(); ?>It is possible to override form settings directly in PHP by passing the setting key and its value.
acfe_form(array(
'name' => 'my-form', // Call by name
'uploader' => 'basic', // Force Uploader to basic
'submit_value' => 'Submit Form', // Change Submit text
'map' => array( // Change field settings
'field_621a65cc5521e' => array(
'label' => 'New label',
'instructions' => 'New instructions',
'value' => 'New default value'
),
)
));You can pass custom data to the form during the form render to retrieve it later in the Form UI or in PHP hooks. Usage example:
acfe_form(array(
'name' => 'my-form',
'my_user' => get_current_user_id() // Add Current User ID
));Custom data can also be passed using the acfe/form/load filter. See documentation. Usage example:
add_filter('acfe/form/load/form=my-form', 'my_form_settings', 10, 2);
function my_form_settings($form, $post_id){
// Add Current User ID
$form['my_user'] = get_current_user_id();
// Return
return $form;
}These data can then be retrieved in the Form UI using the Template Tag {form:my_key} or in PHP hooks using the $form['my_key'] parameter. Usage example:
// form submission
add_action('acfe/form/submit/form=my-form', 'my_form_submit', 10, 2);
function my_form_submit($form, $post_id){
// retrieve 'my_user' data
$my_user = $form['my_user'];
// retrieve form 'name'
$name = $form['name'];
// retrieve form 'submit_value'
$submit_value = $form['submit_value'];
// do something...
}See our guide on Passing Fata to a Form for more details and examples.
It is possible to display the form based on classic PHP conditions. In this example, the form will be only displayed when the current user is also the current post author:
// retrieve user & post author info
$current_user_id = get_current_user_id();
$post_author_id = get_the_author_meta('ID');
// check if the current user is also the post author
if($current_user_id === $post_author_id){
// render form
acfe_form('my-form');
}Conditions can also be set using the acfe/form/load filter. See documentation. Usage example:
add_filter('acfe/form/load/form=my-form', 'my_form_settings', 10, 2);
function my_form_settings($form, $post_id){
// retrieve user & post author info
$current_user_id = get_current_user_id();
$post_author_id = get_the_author_meta('ID');
// check if the current user is different from the post author
if($current_user_id !== $post_author_id){
// hide the form
return false;
}
// return
return $form;
}You can use the [acfe_form] shortcode in order to display the form in the WordPress Editor. Usage example:
// Using Form Name
[acfe_form name="my-form"]
// Using Form ID
[acfe_form ID="120"]Just like the PHP integration, it is possible to override form settings directly from the shortcode. Usage example:
[acfe_form name="my-form" uploader="basic" submit_value="Submit Form"]To pass custom data, simply add the custom key within the shortcode. These data can then be retrieved in the UI using the {form:my_key} Template Tag or in PHP hooks using the $form['my_key'] parameter.
[acfe_form name="my-form" my_user="12"]In order to conditionally display a form using the [acfe_form] shortcode, the acfe/form/load filter should be used. See documentation.
In this hook, when using return false the form will not be displayed, and when using return $form the form will be displayed. In this example, the form will be only displayed when the current user is also the current post author:
add_filter('acfe/form/load/form=my-form', 'my_form_settings', 10, 2);
function my_form_settings($form, $post_id){
// retrieve user & post author info
$current_user_id = get_current_user_id();
$post_author_id = get_the_author_meta('ID');
// check if the current user is different from the post author
if($current_user_id !== $post_author_id){
// hide the form
return false;
}
// display form normally
return $form;
}$args = array(
'ID' => 2274,
'name' => 'my-form',
'title' => 'My Form',
'post_id' => 410,
'field_groups' => array(
'group_61170173ec47f',
),
'field_groups_rules' => false,
'post_field_groups' => false,
'form' => true,
'html_before_fields' => '',
'custom_html_enabled' => false,
'custom_html' => false,
'html_after_fields' => '',
'form_submit' => true,
'submit_value' => 'Submit',
'html_submit_button' => '<input type="submit" class="acf-button button button-primary button-large" value="%s" />',
'html_submit_spinner' => '<span class="acf-spinner"></span>',
'hide_error' => false,
'hide_unload' => false,
'hide_revalidation' => false,
'errors_position' => 'above',
'errors_class' => '',
'updated_message' => '<p>Success!</p>',
'html_updated_message' => '<div id="message" class="updated">%s</div>',
'updated_hide_form' => false,
'honeypot' => true,
'kses' => true,
'uploader' => 'default',
'field_el' => 'div',
'label_placement' => 'top',
'instruction_placement' => 'label',
'form_attributes' => array(
'id' => '',
'class' => 'acfe-form acf-form',
'action' => '',
'method' => 'post',
'data-fields-class' => '',
'data-hide-error' => false,
'data-hide-unload' => false,
'data-hide-revalidation' => false,
'data-errors-position' => 'above',
'data-errors-class' => '',
),
'fields_attributes' => array(
'wrapper_class' => '',
'class' => '',
),
);The Shortcode display a placeholder within the WordPress Editor.
It is possible to display a form preview directly within the WordPress editor using the Shortcode Preview setting.
The Shortcode Preview setting is disabled by default. It can be enabled and disabled in the Settings UIPRO, or with the following code:
add_action('acf/init', 'my_acfe_modules');
function my_acfe_modules(){
// Enable Shortcode Preview for all Forms
acf_update_setting('acfe/modules/forms/shortcode_preview', true);
// Enable Shortcode Preview for all Forms
acf_update_setting('acfe/modules/forms/shortcode_preview', array());
// Enable Shortcode Preview for specific Forms
acf_update_setting('acfe/modules/forms/shortcode_preview', array('my-form'));
}