Develop Your Own Custom Fields Within Gutenberg -WordPress Block Editor
A step-by-step guide
Gutenberg block editor, the new WordPress block page editor, has recently become popular among developers. The reason: it’s a simple way to integrate React inside custom blocks, custom panels, and other Gutenberg interfaces, which are now extendable via hooks and functions.
You can add custom fields to your post fields in Gutenberg with some plugins, such as Advanced Custom Fields or Carbon Fields. However, if you want to develop your own fields, with custom logic as a Gutenberg plugin, you must write some boilerplate code.
The hooks and actions apply a similar architecture as PHP’s hooks and filters. But, due to the nature of JavaScript (JS), React, and the asynchronous calls to the WordPress JS helper function, things can get complex fast.
This guide will help simplify them. We will walk you through the hooks and filters that the Simple Guten fields concept plugin leverages to render the fields to allow you to create your custom code.
The Guten fields concept plugin supports text fields, select fields, media fields, color picker fields, and a repeater field, which can be modified to any field type you want with some React and PHP modifications. If you not familiar with React yet, this could be your chance to dive in!
To add custom fields to Gutenberg Editor, we need to take two steps:
- Add Fields to the REST API
The meta field you are registering must be available in the REST API endpoint of the post — since Gutenberg is updating the fields via the REST API. This is achieved with register_post_meta.
As you can see in the code below, the fields are set to default text fields. This can be overridden by field arguments passed from the hook, which add the meta fields. The filter sgf_register_fields is registering the fields we added in the register_fields.php file with add_filter( ‘sgf_register_fields’, ‘sgf_post_fields’ ).
The filter sgf_register_fields is registering the fields we added in the register_fields.php file with add_filter( ‘sgf_register_fields’, ‘sgf_post_fields’ )
2. Register a Gutenberg Plugin to Add the Fields to Editor
You can add the fields to the front-end with two steps:
Step 2.1: Pass the fields to the block editor’s front-end JS via wp_localize_script. This hook was initially created to pass the front-end 18 transition strings, and it is widely used to pass variables to JS apps. The hook prints a global JS variable with the data passed, allowing the app to access the variable and use the data.
Step 2.2: Render Gutenberg plugins with the field’s data passed from the backend in the variable sgf_data.
As you can see in the code below, we loop over the field’s data and render the appropriate components with an index, matched by the control value in the field’s data.
index.js — main plugin file
ContorolsIndex.js
This file is used to map between the field attribute “control” and the corresponding React component, rendering the file within the Gutenberg panel.
This is a simple text field. The component contains logic to manage two types of rendering: the first is a simple render that fetches and saves the data to a meta field. The second handles the render inside a repeater, fetched by the code, which then updates the values from inner values inside an array of the metadata by key.
This control allows for the addition of multiple repeatable fields inside one meta key. Currently, the only inner control supported is text control.
You can see that the file has logic buttons that dynamically add and remove repeating fields.
The Gutenberg media upload component stores the media with a Post ID. This is a wrapper for the Gutenberg media upload component which converts the Post ID to an image URL. It has some extra logic for an image placeholder via the Gutenberg select API from the wp.data library.
Let’s see the field controls from register-fields.php in action!
You can find more details about the plugin and development in the readme file.
Note: This plugin’s purpose is to demonstrate a concept, do not use it as-is on a live site.
