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