Registering Advanced Custom Fields

Intro

Alloy Core provides wrapper functions for the ACF PHP functions. There are a couple of reasons for this:

• It streamlines the addition of fields
• It reduces the overall code footprint

Registering the fields via PHP is preferred versus the WordPress GUI simply for the fact it makes them extremely portable and reusable. You can copy and paste them from template to template or project to project. When you deploy to staging or production you don't have to worry about messing with the database or any importing to get your fields.

Creating your custom fields file

Custom fields are defined under app/custom-fields. Each file in this directory is automatically loaded so you just need to have your file present. In these examples we'll be adding a basic contact page. So you'd create a file called template-contact.acf.php.

Defining your field group

The first thing you'll need to do is set your group options. There are quite a few options you can set but generally you'll just use title, location and hide_on_screen if you're removing things from the UI. You can add any other group options ( see the ACF documentation ) but this is all that's required to get started. Let's work on our contact page:

$group_args = [
	'title'          => 'Contact Page Options',
	'location_is'    => [ 'page_template', 'template-contact.php' ],
	'hide_on_screen' => [ 'the_content' ]
];

You can see we set hide_on_screen to the_content since we won't have any content sections on the contact page.

Setting the location

Alloy Core makes it easy to set your location if it's a one to one set up through a location_is parameter. For example, if you just need to set it to the front page you'd do:

'location_is' => [ 'page_type', 'front_page' ]

Where it gets complicated is when you need multiple location rules. To do that you'd use the standard ACF location parameter:

'location'    => [
	[
		[
			'param' => 'page_type',
			'operator' => '!=',
			'value' => 'posts_page'
		],
		[
			'param' => 'page_type',
			'operator' => '!=',
			'value' => 'front_page'
		],
		[
			'param' => 'page_template',
			'operator' => '==',
			'value' => 'default'
		]
	]
]

Adding Fields

Once you have your group set up you can begin adding fields in. For our working example it's a very simple contact page so we just need somewhere for them to add their form code:

$fields = [
	[ 'textarea', 'Form Code' ]
];

The syntax for adding fields is really quite simple. By default you just need to define a field type and a field label:

[ 'field_type', 'field_label' ]

In our "Form Code" example above Alloy Core would grab the label and convert it to "form_code". So you would be able to grab it with PHP like this:

$formcode = get_field('form_code');

There is an optional third parameter which is an array of additional parameters. For example let's say we don't want to grab the field using form_code. Let's say we want it to be more specific:

$fields = [
	[ 'textarea', 'Form Code', [ 'name' => 'contact_form_code' ] ]
];

Now we would grab the value of the field using get_field('contact_form_code'). The third parameter can contain any additional parameter that's not field type or label.

Registering your field group

Now that you have set your group options and defined some fields you can register them together:

$field_group = core_register_field_group( 'contact-acf', $group_args, $fields );

core_register_field_group takes your group settings and your fields and registers them through ACF. The first parameter must be unique to this field group - typically you can name it after what ever you are working on. If it isn't unique then you could have conflicts if your fields have the same names.

Pro tip: If you're having trouble with your custom fields you can log the output of core_register_field_group to get more information. Going off of our example above:

_log( $field_group );

Examples

Text

[ 'text', 'Text Field' ]

Textarea

[ 'textarea', 'Textarea Field' ]

Image

[ 'image', 'Background Image', [
	'return_format' => 'url',
	'instructions' => 'Dimensions: 800x200. Recommended format: JPG'
] ]

Select Field

[ 'select', 'Pick an option', [
	'choices' => [
		'pickme' => 'Pick me!',
		'nopickme' => 'No pick me!'
	]
] ]

Repeater Field

[ 'repeater', 'Files', [
	'sub_fields' => [
		[ 'text', 'File URL' ],
		[ 'textarea', 'File Description' ]
	],
	'max' => 4,
	'layout' => 'block',
	'button_label' => 'Add Link or File'
] ]

Flexible Content

[ 'flexible_content', 'Content Blocks 123', [
	'button_label' => 'Add Block',
	'layouts' => [

		[ 'Hero', [
			'display' => 'block',
			'sub_fields' => [

				[ 'text', 'Heading' ],
				[ 'textarea', 'Description' ]

			]
		] ],

		[ 'Intro', [
			'layout' => 'block',
			'sub_fields' => [

				[ 'text', 'Heading' ],
				[ 'textarea', 'Description' ]

			]
		] ]

	]
] ]

Tips

• The ACF PHP documentation isn't comprehensive. If you're ever stuck on what parameters a field needs you can quickly through a field together in the WordPress GUI and then export it as JSON or generate it as PHP. This will show you all of the parameters available to that field. Be sure to delete it from the WordPress GUI after.
• Be sure to prefix fields where needed. For example if a page has an intro section and a team section and they both have a "heading" you can't have both fields just be [ 'text', 'Heading' ] this will cause one to be overwritten by the other. Instead you would do [ 'text', 'Heading', [ 'name' => 'intro_heading' ] ] and [ 'text', 'Heading', [ 'name' => 'team_heading' ] ]