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.