Documentation

acf_form()

This article is available in different versions. Currently viewing

Overview

This function creates a form to add or update a post. There are many settings available to customize the form and these are set by adding to the $options array as explained below.

Parameters

<?php acf_form( $options ); ?>
  • $options (array) an array containing 1 or more of the following settings. optional

$options

$options = array(

	/* (string) Unique identifier for the form. Defaults to 'acf-form' */
	'id' => 'acf-form',
	
	/* (int|string) The post ID to load data from and save data to. Defaults to the current post ID. 
	Can also be set to 'new_post' to create a new post on submit */
	'post_id' => false,
	
	/* (array) An array of post data used to create a post. See wp_insert_post for available parameters.
	The above 'post_id' setting must contain a value of 'new_post' */
	'new_post' => false,
	
	/* (array) An array of field group IDs/keys to override the fields displayed in this form */
	'field_groups' => false,
	
	/* (array) An array of field IDs/keys to override the fields displayed in this form */
	'fields' => false,
	
	/* (boolean) Whether or not to show the post title text field. Defaults to false */
	'post_title' => false,
	
	/* (boolean) Whether or not to show the post content editor field. Defaults to false */
	'post_content' => false,
	
	/* (boolean) Whether or not to create a form element. Useful when a adding to an existing form. Defaults to true */
	'form' => true,
	
	/* (array) An array or HTML attributes for the form element */
	'form_attributes' => array(),
	
	/* (string) The URL to be redirected to after the form is submit. Defaults to the current URL with a GET parameter '?updated=true'.
	A special placeholder '%post_url%' will be converted to post's permalink (handy if creating a new post) */
	'return' => '',
	
	/* (string) Extra HTML to add before the fields */
	'html_before_fields' => '',
	
	/* (string) Extra HTML to add after the fields */
	'html_after_fields' => '',
	
	/* (string) The text displayed on the submit button */
	'submit_value' => __("Update", 'acf'),
	
	/* (string) A message displayed above the form after being redirected. Can also be set to false for no message */
	'updated_message' => __("Post updated", 'acf'),
	
	/* (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',
	
	/* (string) Determines where field instructions are places in relation to fields. Defaults to 'label'. 
	Choices of 'label' (Below labels) or 'field' (Below fields) */
	'instruction_placement' => 'label',
	
	/* (string) Determines element used to wrap a field. Defaults to 'div' 
	Choices of 'div', 'tr', 'td', 'ul', 'ol', 'dl' */
	'field_el' => 'div',
	
	/* (string) Whether to use the WP uploader or a basic input for image and file fields. Defaults to 'wp' 
	Choices of 'wp' or 'basic'. Added in v5.2.4 */
	'uploader' => 'wp'
	
);

Notes

It is important to note that whilst the acf_form() function will create a form allowing you to input data, it will not perform the logic needed to save the data. This logic is handled by another function called acf_form_head(). To allow the form to save data, you will need to place the acf_form_head() function at the top of your page template before any HTML is rendered.

Examples

Basic

This example shows a basic acf_form to edit the current post.

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

	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">

			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>

				<?php acf_form(); ?>

			<?php endwhile; ?>

		</div><!-- #content -->
	</div><!-- #primary -->

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

Editing a specific post

This example shows how to target a specific post, customize the button label and hide the post title input.

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

	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">

			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>

				<?php acf_form(array(
					'post_id'	=> 123,
					'post_title'	=> false,
					'submit_value'	=> 'Update the post!'
				)); ?>

			<?php endwhile; ?>

		</div><!-- #content -->
	</div><!-- #primary -->

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

Create a new post

This example shows how you can create a new post when submitting the form.

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

	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">

			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>

				<?php acf_form(array(
					'post_id'		=> 'new_post',
					'new_post'		=> array(
						'post_type'		=> 'event',
						'post_status'		=> 'publish'
					),
					'submit_value'		=> 'Create a new event'
				)); ?>

			<?php endwhile; ?>

		</div><!-- #content -->
	</div><!-- #primary -->

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

Appending with AJAX

When using AJAX to append the acf_form HTML, please note that some extra PHP/JS must also be run to let ACF know there are new fields on the page which may require some JS initializing.

PHP

Please add the following code to the page within the <body> tags and before the wp_footer action. This will create a hidden WYSIWYG field and enqueue the required JS templates for the WP media popups.

PHP

acf_enqueue_uploader();

Javascript

Either place the following inline JS in the appended HTML, or run the JS on complete of your AJAX append. This will allow ACF to initialize the fields within the newly added HTML.

Javascript

<script type="text/javascript">
(function($) {
	
	// setup fields
	acf.do_action('append', $('#popup-id'));
	
})(jQuery);	
</script>

Related