The new block-based editor in WordPress provides a great new content editing experience, and it’s even more powerful with custom blocks.
What is Advanced Custom Fields
Advanced Custom Fields is a plugin for building additional content editing fields throughout the WordPress interface. You can build custom metaboxes, site options, user profile fields, and term metadata.
For a more detailed walkthrough of ACF and how it compares to similar plugins, see my Introduction to Custom Metaboxes. I plan to write more about ACF in the near future, so keep an eye on my Advanced Custom Fields category page.
ACF is the first popular metabox plugin to add support for building blocks. Other plugins are working on it as well – see CMB2 and Carbon Fields articles on Gutenberg compatibility – but ACF is leading the way.
Developer's Guide to Gutenberg
I walk you through the technical details and code snippets you need as a WordPress developer building a Gutenberg website.
Creating a block
There are three key parts to building a Gutenberg block with ACF:
- Register the block with PHP
- Build the block editor with the ACF user interface
- Describe how the block is rendered using PHP
I’ll walk you through each step required to build a simple “Team Member” block.
I’m storing the block’s markup and styles inside the theme to keep things simple, but you could also place the code in a core functionality plugin.
Register the block
We’ll use the
acf_register_block_type() to register our custom block. I’ve provided a summary of the parameters below, and for more information see the ACF documentation.
You must have ACF 5.8 or later installed for this to work.
This is your unique name for the block. ACF automatically namespaces it for you, so my
team-member name becomes
acf/team-member in the database.
This is the title shown in the Gutenberg block editor.
The template file used to render the block. The same template file will be used on the frontend and as the “Preview” view in the backend editor. This can either be a relative URL from the current theme, as shown above, or a full path to any file.
Alternatively, you can use the render_callback parameter to specify a function name that output’s the block’s HTML.
This determines in which section of the “Add Block” window it appears. The options provided by WP core are: common, formatting, layout, widgets, and embed.
Specify a dashicons icon to use, or a custom SVG icon.
This lets you control how the block is presented the Gutenberg block editor. The default is “auto” which renders the block to match the frontend until you select it, then it becomes an editor.
If set to “preview” it will always look like the frontend and you can edit content in the sidebar.
If set to “Edit” it appears like a metabox in the content area. The user can switch the mode by clicking the button in the top right corner, unless you specifically disable it with
'supports' => array( 'mode' => false ).
Up to three additional terms to use when a user is searching for the block. The name is always indexed so you don’t need to repeat it as a keyword here.
Build the block editor
Once the block has been registered, you can now go to Custom Fields in the admin and create your block editor. It works just like a standard metabox built in ACF.
Under the location rules, select “Block” is equal to “Team Member”.
Build the block markup
The final step is to write the markup for the block. I created a template partial in
/partials/block-team-member.php , matching the
render_template parameter I specified when registering the block. My template partial looks like:
get_field() function to access the fields set in the block settings. You can then build the markup for your block based on your specific design requirements.
Building a Table of Contents block
In my article on Developing a Gutenberg Website I mentioned the Table of Contents block I built for a few clients. It dynamically lists all h2’s within the current article and links to each one.
I started by forking the WP Anchor Header plugin. My changes include:
- Limiting it to only h2’s
- Only running on posts that have the table-of-contents block.
- Before automatically adding an ID to each heading, check if one exists already. Clients can manually specify the heading’s anchor link in the Gutenberg editor so we should respect that.
ea_table_of_contents()function accepts a
$countparameter. We use this to list the first few headings in the article on the homepage
The block doesn’t have any editable fields so I added a Message field describing how it works:
Here is the full code for the table of contents block.