Overview
The Advanced Custom Fields plugin is packed with loads of useful field types such as text, image and WYSIWYG. However, when working on a project, it may be necessary to create a new type of field to save & load unique data.
This guide will demonstrate how to create a new field type for the ACF plugin.
Download
To make life easier, we put together a comprehensive starter-kit for creating an ACF field type. This starter-kit contains all the necessary files to create a WP plugin and is heavily commented so you can build your field type quickly and confidently!
Field Type Template on Github
Please download a copy of the ACF field type template starter-kit from this Github repository (Click the Green Download Zip button).
https://github.com/AdvancedCustomFields/acf-field-type-templateOnce downloaded, take a look around. Here is a list of the files and folders included.
| Name | Description |
|---|---|
| acf-FIELD-NAME | The plugin folder. |
| /assets | The folder for including assets. This folder contains 3 sub folders called css, js and images. These can be modified, renamed or removed. |
| /fields | The folder for field class files. Each major version of ACF has introduced improvements to the acf_field class which are not always backwards compatible. This folder contains 2 field class files for ACF-v4 and ACF-v5. |
| /lang | The folder for translation files (.pot, .po, .mo). |
| /acf-FIELD-NAME.php | The main plugin file. This file contains plugin meta information, defines settings and includes the relevant field class file. |
| /README.md | A simple readme file for your Github repository |
| /readme.txt | A simple readme file for your WP plugin |
Setup
With the starter-kit downloaded and extracted, the next step is to setup the basic configuring for your field type plugin.
The starter-kit uses placeholders (such as FIELD_NAME) throughout the folders, files names and code. Use the following list of placeholders to do a “find and replace” on each file’s name and contents.
| Name | Description | Example |
|---|---|---|
NAMESPACE |
Short single word used in class names to avoid conflicts. | “my” |
FIELD_NAME |
Single word, no spaces. Underscores allowed. | “icon_picker” |
FIELD-NAME |
Slug friendly version of the above used for folder and file names. | “icon-picker” |
FIELD_LABEL |
Multiple words, can include spaces, visible when selecting a field type. | “Icon Picker” |
TEXTDOMAIN |
Unique identifier for retrieving translated strings. For best compatibility with wordpress.org, please use your plugin slug (plugin folder name). eg. acf-FIELD-NAME | “acf-icon-picker” |
PLUGIN_URL |
Url to the github or WordPress repository. | |
PLUGIN_TAGS |
Comma seperated list of relevant tags used for search results on wordpress.org | |
SHORT_DESCRIPTION |
Brief description of the field type, no longer than 2 lines. | |
EXTENDED_DESCRIPTION |
Extended description of the field type. | |
AUTHOR_NAME |
Name or wordpress.org username of the author | |
AUTHOR_URL |
URL to author’s website |
After all placeholders have been modified, you should be left with a plugin containing all the logic for a custom field type! Before diving into any code, first copy this plugin into your WordPress plugins folder (wp-content/plugins) and activate it.
Customize
With your new field type activated and available for selection, it’s time to customize the UI and functionality.
All logic for your field’s appearance and functionality is defined in the fields/class-xxx-v5.php file. This class is packed full of powerful functions which allow you to customize how data is saved and displayed! Each function is documented with internal comments, so it is best to open up the file and read it over top to bottom. Please note that most functions are commented out. This allows you to un-comment and use only the functions that you need.
Here is a quick overview of the functions:
| Name | Description |
|---|---|
__construct |
Initialize function which sets the field’s data such as name, label, category and defaults |
render_field_settings |
Create extra settings for your field. These are visible when editing a field |
render_field |
Create the HTML interface for your field |
input_admin_enqueue_scripts |
Enqueue CSS + JavaScript to assist your render_field() function |
input_admin_head |
Add inline CSS and JavaScript to assist your render_field() function |
input_form_data |
Add hidden inline HTML |
input_admin_footer |
Add inline CSS and JavaScript to assist your render_field() function |
load_value |
This filter is applied to the $value after it is loaded from the db |
update_value |
This filter is applied to the $value before it is saved in the db |
format_value |
This filter is applied to the $value before being returned to template API |
validate_value |
This filter is used to perform validation on the value prior to saving |
delete_value |
This action is fired after a value has been deleted from the db |
The above are only some of the functions available in the acf_field class. Please read over the extended comments found above each function to learn more.