Documentation

Creating a new field type

Currently viewing documentation for Advanced Custom Fields

Overview

The Advanced Custom Fields plugin comes packed with lots of useful field types such as text, image and WYSIWYG. However, when working on a project, it may be necessary to define a new type to save & load data.

This guide will demonstrate how to create a new field type for the ACF plugin.

Download

To make life easier, we have put together a free 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.

Please download a copy of this starter-kit here: https://github.com/elliotcondon/acf-field-type-template. (Click the Download Zip button )

After the starter-kit has downloaded, please extract the .zip file and move the folder called acf-field-type-template-master to your wp-content/plugins directory.

Structure

The starter-kit contains the following files and folders. Here is a brief explanation of each:

  • /css: folder for .css files.
  • /images: folder for image files
  • /js: folder for .js files
  • /lang: folder for .pot, .po and .mo files
  • acf-FIELD_NAME.php: Main plugin file that includes the correct field file based on the ACF version
  • FIELD_NAME-v5.php: Field class compatible with ACF version 5
  • FIELD_NAME-v4.php: Field class compatible with ACF version 4
  • readme.txt: WordPress readme file to be used by the wordpress repository

Setup

The starter-kit uses PLACEHOLDERS such as FIELD_NAME throughout the file names and code. Use the following list of placeholders to do a ‘find and replace’ on each file’s name and contents:

  • FIELD_NAME: Single word, no spaces. Underscores allowed. eg. donate_button
  • FIELD_LABEL: Multiple words, can include spaces, visible when selecting a field type. eg. Donate Button
  • PLUGIN_URL: Url to the github or WordPress repository
  • PLUGIN_TAGS: Comma seperated list of relevant tags
  • DESCRIPTION: Brief description of the field type, no longer than 2 lines
  • EXTENDED_DESCRIPTION: Extended description of the field type
  • AUTHOR_NAME: Name of field type author
  • AUTHOR_URL: URL to author’s website

Last but not least, rename the acf-field-type-template-master folder to acf-FIELD_NAME where FIELD_NAME is also a placeholder.

Congratulations. Your field type plugin is ready for testing! Please login to your WP website and activate the acf-FIELD_NAME plugin. With the plugin activated, you will now see a new field type available when creating a field in the Advanced Custom Fields plugin.

Customize

With your new field type activated and available for selection, it’s time to customize the UI and functionality.

The acf-FIELD_NAME-v5.php 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:

  • __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_NAME-v5.php class. Please read over the extended comments found above each function to learn more.

Share

If you think your field type may benefit others, please be sure to post a thread on the Community Forum for a chance to be added to the add-ons page.