Documentation

acf_form()

Currently viewing documentation for Advanced Custom Fields

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 an optional array containing 1 or more of the settings below

  • id A unique identifier for the form. Defaults to ‘acf-form’
  • post_id The post ID to load data from and save data to. Defaults to the current post. Can also be set to ‘new_post’ to create a new post on submit
  • new_post An array of post data used to create a post. See wp_insert_post for available parameters. post_id param must be set to ‘new_post’
  • field_groups An array of field group IDs to override the field’s which would normally be displayed for the post
  • fields An array of field Keys or IDs to override the field’s which would normally be displayed for the post
  • post_title Whether or not to show the post title text field. Defaults to false
  • post_content Whether or not to show the post content editor. Defaults to false
  • form Whether or not to create a form element. Useful when hard-coding the form element Defaults to true.
  • form_attributes An array or HTML attributes for the form element.
  • return The URL to be redirected to after the post is created / updated. Defaults to the current URL with an extra GET parameter called updated=true. A special placeholder of %post_url% will be converted to post’s permalink (handy if creating a new post)!
  • html_before_fields A string containing extra HTML to add before the fields
  • html_after_fields A string containing extra HTML to add after the fields
  • submit_value A string containing the text displayed on the submit button
  • updated_message A string message which id displayed above the form after being redirected
  • label_placement Whether to display labels above (top) or beside (left) fields. Defaults to top
  • instruction_placement Whether to display instructions below the label or field. Defaults to label
  • field_el The element used to wrap a field. Choose from div, tr, ul, ol, dl. Defaults to div

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();

Javascipt

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>