acf_register_form()

Documentation Functions acf_register_form()

Last updated Feb 17, 2022

Description

Registers a form for use with the acf_form() function. There are many settings available to customize a form which are set by adding to the $settings array (see below).

Parameters

<?php acf_register_form( $settings ); ?>

$settings

(String | Array) Array of settings or ‘id’ of a registered form.

• id
  (String) A unique identifier for the form. Defaults to ‘acf-form’.

  'id' => 'acf-form',

• post_id
  (Integer | String) The post ID used to determine which fields to show, where data is loaded, and where data is saved. Defaults to current post ID. Can also be sent to ‘new_post’ to create a new post on submit.

  'post_id' => false,

• new_post
  (Array) When the above attribute is set to "new_post", this setting is used to create the post. See wp_insert_post for available parameters.

  'new_post' => false,

• field_groups
  (Array) An array of field group IDs/keys to override the fields displayed in this form.

  'field_groups' => false,

• fields
  (Array) An array of field IDs/keys to override the fields displayed in this form.

  'fields' => false,

• post_title
  (Boolean) Whether or not to show the post title text field. Defaults to false.

  'post_title' => false,

• post_content
  (Boolean) Whether or not to show the post content editor field. Defaults to false.

  'post_content' => false,

• form
  (Boolean) Whether or not to create a form element. Useful when adding to an existing form. Defaults to true.

  'form' => true,

• form_attributes
  (Array) An array or HTML attributes for the form element.

  'form_attributes' => array(),

• return
  (String) The URL to be redirected to after the form is submitted. Defaults to the current URL with a GET parameter ‘?updated=true’.
  A special placeholder ‘%post_url%’ will be converted to post’s permalink.
  A special placeholder ‘%post_id%’ will be converted to post’s ID.

  'return' => '',

• html_before_fields
  (String) Extra HTML to add before the fields.

  'html_before_fields' => '',

• html_after_fields
  (String) Extra HTML to add after the fields.

  'html_after_fields' => '',

• submit_value
  (String) The text displayed on the submit button.

  'submit_value' => __("Update", 'acf'),

• updated_message
  (String) The message displayed above the form after being redirected. Can also be set to false for no message.

  'updated_message' => __("Post updated", 'acf'),

• label_placement
  (String) Determines where field labels are places in relation to fields. Defaults to ‘top’. Choices of ‘top’ (above fields) or ‘left’ (beside fields).

  'label_placement' => 'top',

• instruction_placement
  (String) Determines where field instructions are placed in relation to fields. Defaults to ‘label’. Choice of ‘label’ (below labels) or ‘field’ (below fields).

  'instruction_placement' => 'label',

• field_el
  (String) Determines element used to wrap a field. Defaults to ‘div’. Choices of ‘div’, ‘tr’, ‘td’, ‘ul’, ‘ol’, ‘dl’.

  'field_el' => 'div',

• uploader
  (String) Whether to use the WP uploader or a basic input for image and file fields. Defaults to ‘wp’ . Choices of ‘wp’ or ‘basic’.

  'uploader' => 'wp',

• honeypot
  (Boolean) Whether to include a hidden input field to capture non-human form submission. Defaults to true.

  'honeypot' => true,

• html_updated_message
  (String) The HTML used to render the updated message.

  'html_updated_message'  => '<div id="message" class="updated"><p>%s</p></div>',

• html_submit_button
  (String) The HTML used to render the submit button.

  'html_submit_button'  => '<input type="submit" class="acf-button button button-primary button-large" value="%s" />',

• html_submit_spinner
  (String) The HTML used to render the submit button loading spinner.

  'html_submit_spinner' => '<span class="acf-spinner"></span>',

• kses
  (Boolean) Whether or not to sanitize all $_POST data with the wp_kses_post() function. Defaults to true.

  'kses' => true

Changelog

• kses added in version 5.6.5.
• uploader added in version 5.2.4.
• honeypot added in version 5.3.4
• html_updated_message, html_submit_button, and html_submit_spinner added in version 5.5.10

Examples

Basic usage

This example demonstrates how to register a form in the functions.php file and later display that form within a page template.

functions.php

add_action('acf/init', 'my_acf_form_init');
function my_acf_form_init() {

    // Check function exists.
    if( function_exists('acf_register_form') ) {

        // Register form.
        acf_register_form(array(
            'id'       => 'new-event',
            'post_id'  => 'new_post',
            'new_post' => array(
                'post_type'   => 'event',
                'post_status' => 'publish'
            ),
            'post_title'  => true,
            'post_content'=> true,
        ));
    }
}

page-new-event.php

<?php acf_form_head(); ?>
<?php get_header(); ?>

<div id="primary" class="content-area">
    <div id="content">
        <?php acf_form('new-event'); ?>
    </div><!-- #content -->
</div><!-- #primary -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Related

• Functions: acf_form_head()
• Guides: Create a front end form