How To Create Custom Field Type For Advanced Custom Fields Pro

How to create custom ACF field type

One of the great features of the Advanced Custom Fields plugin is that we can easily extend it and create new field types. With available starter-kit, we can create new field type within few minutes. In this tutorial, I will show you how to create new field type for the Advanced Custom Fields Pro plugin which will have a list of Maps Marker Pro layers or markers. The Maps Marker Pro is a mapping plugin for displaying locations and routes on WordPress website, and the ACF field type that we are going to build will enable us to have better user experience for adding maps in our content.

 

Starter-kit

To ease the process of creating new field types, author of ACF plugin provided us with a starter-kit which we can use as a base for creating a new field. The starter-kit can be downloaded from this address https://github.com/elliotcondon/acf-field-type-template.
We need to download the zip file and extract the acf-field-type-template-master folder to wp-content/plugins directory. We will not activate the plugin yet because there are some things we need to change. The code and filenames use placeholders like FIELD_NAME which needs to be changed to appropriate values with help of ‘find and replace’ technique before we activate this plugin.

Since our field will be tied with Maps Marker Pro plugin, we will name it Mapsmarker and change FIELD_LABEL placeholder to Mapsmarker and FIELD_NAME into mapsmarker. The list of placeholders which we need to change and appropriate types of values that we can use can be found on the Github page from which we have downloaded the starter-kit.

We also need to make sure that we change plugin directoy name from acf-field-type-template-master to acf-mapsmarker, name of the acf-FIELD_NAME.php and also name of the two .php files acf-FIELD_NAME-v4.php and acf-FIELD_NAME-v5.php which can be found in fields directory.

Now that we have downloaded the code, extracted it into plugins directory and changed placeholders, we can start developing its functionality.

 

Field Settings

Each ACF field type comes with default field settings such as field name, default value, whether the field is required or not and etc. We can also add our own custom settings to each existing field or to the new one that we create. The Maps Marker Pro plugin allows us to display a map with only one marker on frontend or layer map which consists of multiple markers. Because of that, we will create a custom setting for our field where we can choose between marker and layer.

What we need to do is to open acf-mapsmarker/fields/acf-mapsmarker-v5.php file where we will add our code. Since we are creating field type for ACF Pro version, we will only work on V5 file and not on v4. First thing that we will change is the category setting from “basic” to “relational” on line 47 $this->category = 'relational';. This will put our field type into the Relational category in Field Type setting drop-down.

1. Field type category

 

Next thing wee need to change is list of defaut settings values. On line 54 there is property with array of deufault values, in which we already have example for font size $this->defaults = array(
'font_size' => 14,
);
, we can relpace 'font_size' with the 'map_type' and 14 with the 'layer'.

The result should look like this:
$this->defaults = array(
'map_type' => 'layer',
);
.

The 'map_type' will be the name of our custom settings which we will create next, and 'layer' will be default value for our setting.

To create custom settings, we need to look for render_field_settings method in the code. This method already has a piece of code as an example which we can delete.
The code that needs to be deleted looks like this:

acf_render_field_setting( $field, array(
'label' => __('Font Size','acf-cf7'),
'instructions' => __('Customise the input font size','acf-cf7'),
'type' => 'number',
'name' => 'font_size',
'prepend' => 'px',
));

Now that we removed that piece of code, we can start writing our own code. We will also call acf_render_field_setting method in which will render drop-down where we will be able to choose between Layer and Marker type of the map.
The code which we need to add looks like this:

acf_render_field_setting( $field, array(
'label' => __('Map Type','acf-mapsmarker'),
'instructions' => __('Choose Marker or Layer map','acf-mapsmarker'),
'type' => 'select',
'name' => 'map_type',
'choices' => [
'marker' => 'Marker',
'layer' => 'Layer'
],
) );
You can see that name 'map_type' matches with the default value settings which we wrote eralier.

We have now categorized our field properly, created custom settings for our field and added the default value for this settings. Next thing that we need to do is to write a code which will be responsible for rendering our field.

 

Render Field

In the render_field method we will write code which will render our field in WordPress administration. The first thing we need to do is to delete example code from this method. Now we can start to write our own code which will render drop-down with a list of Maps Marker Pro layers or markers depending on setting we set when we create this field in administration. To get this list we will use Maps Marker Pro API function like MMPAPI::list_layers(); and for markers MMPAPI::list_markers();. List of all API functions for this plugin can be found here: https://www.mapsmarker.com/wp-content/uploads/mmpapi/

Code for rendering our field looks like this:

First thing that we do is checking whether MMPAPI class exists. If this class doesn’t exist that either means that the Maps Marker Pro plugin is not installed or maybe the API class name has changed. Either way, we need to make sure that this class exists so that we don’t get an error on our website.

Next, we will get a list of layers or markers by checking what is selected in our field settings. If there’s a result we will start to render our field.

Our field should look similar to one on this image.

2. Our field in post/page edit screen

Our field type is now completed and we can star to use it.

 

Render field on frontend

To get field value on front end we will use ACF <code>get_field()</code> function.

Let’s say that we used our field to get a specific Maps Marker layer on the front-end and that we called our field map. The setting for our field would look like this:

3. Field settings example

We can then in our theme write code similar to this one in order to get field value and render Maps Marker map:

Value returned from this field will look like layer="1" which we then can use in [mapsmarker] shortcode.

 

Conslusion

In this tutorial, we have created new field type for Advanced Custom Field Pro plugins by using starter-kit offered by plugin author. This start-kit comes with an example of text input field with which you can easily start to create your own field type and also offers code for Pro version of ACF and the Free version. File with -V5 in its name is used for Pro version and this is the version which I’ve used in this tutorial. I didn’t cover the process of creating new field type for free version in this tutorial because I’ve thought that it deserves space in its own tutorial and if you think that I should write a tutorial on how to create new field type for the free version of Advanced Custom Fields leave a comment.

About the Author

Freelance WordPress developer who offers full stack web development services. Occasionally writes about business and WordPress development. When not in front of the computer can be found on a bicycle or enjoying other outdoor activities.