Building Gutenberg Blocks with Advanced Custom Fields

Gutenberg, the new block-based content editor in WordPress, is even more powerful when you build custom blocks to serve your specific design and content creation needs. Advanced Custom Fields makes it easy to build custom blocks with minimal code and no JavaScript.

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. See this presentation for more information on ACF.

With the introduction of blocks with WordPress 5.0, you can now use ACF to build custom blocks as well.

Examples of custom blocks

How to build custom blocks with ACF

I’ll walk you through building a simple “Team Member” block that includes a name, title, photo, and description.

Purchase and download ACF

Advanced Custom Fields is a premium plugin, so you’ll need to purchase a license from their website. The developer plan is a one-time fee of $100 for lifetime updates and unlimited websites, which is a great deal.

As of right now, version 5.8 of ACF (with block building functionality) is still in beta so follow these steps to download:

1. Go to AdvancedCustomFields.com and log into your account.
2. Under “Licenses and Downloads” click “See all versions”
3. Download the most recent version (currently 5.8.0-beta3)
4. On your website, go to Plugins > Add New > Upload to upload and activate the plugin.

Register the block with PHP

In your theme’s functions.php file or a core functionality plugin, use acf_register_block() to describe your block to ACF. Here’s a summary of the available parameters.

	<?php
	/**
	* Register Blocks
	* @see https://www.billerickson.net/building-gutenberg-block-acf/#register-block
	*
	*/
	function be_register_blocks() {
	if( ! function_exists( 'acf_register_block_type' ) )
	return;
	acf_register_block_type( array(
	'name' => 'team-member',
	'title' => __( 'Team Member', 'clientname' ),
	'render_template' => 'partials/block-team-member.php',
	'category' => 'formatting',
	'icon' => 'admin-users',
	'mode' => 'auto',
	'keywords' => array( 'profile', 'user', 'author' )
	));
	}
	add_action('acf/init', 'be_register_blocks' );

view raw functions.php hosted with ❤ by GitHub

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:

	<?php
	/**
	* Team Member block
	*
	* @package ClientName
	* @author Bill Erickson
	* @since 1.0.0
	* @license GPL-2.0+
	**/
	$name = get_field( 'name' );
	$title = get_field( 'title' );
	$photo = get_field( 'photo' );
	$description = get_field( 'description' );
	echo '<div class="team-member">';
	echo '<div class="team-member--header">';
	if( !empty( $photo ) )
	echo wp_get_attachment_image( $photo['ID'], 'thumbnail', null, array( 'class' => 'team-member--avatar' ) );
	if( !empty( $name ) )
	echo '<h4>' . esc_html( $name ) . '</h4>';
	if( !empty( $title ) )
	echo '<h6 class="alt">' . esc_html( $title ) . '</h6>';
	echo '</div>';
	echo '<div class="team-member--content">' . apply_filters( 'ea_the_content', $description ) . '</div>';
	echo '</div>';

view raw block-team-member.php hosted with ❤ by GitHub