Creating a new field type

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-template

Once 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
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.