Custom Gutenberg Blocks w/ Advanced Custom Fields Blocks Feature

Snapshot

Two ways that you can create new content blocks for Gutenberg are to write the code yourself in JavaScript or use the new Advanced Custom Fields Blocks feature.

At the the time of this writing, the feature is available in ACF Pro V. 5.8 and higher. ACF Pro V. 5.8 is available as Beta-3. When Beta testing is complete and the ACF development team releases the Blocks feature into the wild, their plan is to include it in both the free and PRO versions.

The ACF Blocks feature provides a very easy way for building new content blocks. You don’t have to be a JavaScript expert and you certainly don’t have to drastically alter your development workflow. You get to use what you already know and, as Emeril Lagasse says, “kick it up a notch. BAM!!!”

ACF blocks are especially suitable when building content blocks for client websites where the blocks are meant to be used only on that website. If you are building blocks for a plugin that will be distributed to the world-at-large, the preferred coding method remains JavaScript.

This article shows you how I created an ACF content block for the “Our Captains” page on the Fish-Tale Marina website. In this tutorial, you will learn how to:

• Register your ACF Gutenberg Block with PHP
• Build the editor block with the ACF Field Group user interface
• Render your block on the front end using PHP, HTML, and CSS

Oh yes, did I mention that we’re going to be using CSS Grid for the content layout?

Let’s begin…

Register your ACF Gutenberg Block with PHP

The first step in creating your ACF content block is registering it in PHP. ACF blocks are created with a call to acf_register_block(). Here is the source I created for the Fish-Tale Marina Boat Captain block.

https://gist.github.com/vfontjr/8282ff38fcd391a9c5a49cd721bcf559#file-acf_blocks-php

The documentation for the acf_register_block() can be found here: https://www.advancedcustomfields.com/resources/acf_register_block/

I really want to use a svg icon for this block. The documentation says it’s feasible, but the feature doesn’t work yet. You also can’t use your own .png or .jpg files either. So, if you want an icon on your block, stick to the WordPress Dashicons. It’s the only viable option for now.

I save all ACF block registration code in an external file that I “require_once” in the theme’s functions.php. This allows me to create as many blocks as I need for a site without cluttering functions.php or worrying about changing themes. The source code for this ACF block is in the theme’s /lib/ directory and it’s loaded in functions.php with this line of code:

https://gist.github.com/vfontjr/8282ff38fcd391a9c5a49cd721bcf559#file-functions-php

Build the editor block with the ACF Field Group user interface

Step two is to build the field group. This is the field group for this content block:

Creating the field group is pretty straight forward. The name and description fields are required, and the Website URL displays conditionally when the Website Name has a value.

The one thing that’s different, that you won’t find in ACF Versions earlier than 5.8, is that you can assign this field group in the Location section to the Gutenberg block we registered in Step 1.

That’s all there is to it, for the back end anyway. But here’s a little caveat, before you can actually see your new block in Gutenberg, make sure you’ve completed the first step above and your block registration code is functioning. If you didn’t complete the first step correctly, you will not see the block in the location drop down.

Let’s test our code and see if we can use the new block to create a post. If we did everything right to this point, our new block should show up in Gutenberg’s block list.

Select the block and it should be added to our post, ready to receive content:

Render your block on the front end using PHP, HTML, and CSS

With all the back end work done, it’s time to render the front end. When we registered the block, we included this line in the array:

Here’s the code for block-boat-captain.php render template:

https://gist.github.com/vfontjr/8282ff38fcd391a9c5a49cd721bcf559#file-block-boat-captain-php

This code retrieves the field content from the database, then displays it in standard HTML. If you’ll notice, this particular code is written for columns. In fact, this was originally done for a Genesis Framework child theme. The column classes are standard in the child theme’s style.css.

Earlier I promised to display this content with a CSS Grid layout. Here’s the source code:

https://gist.github.com/vfontjr/8282ff38fcd391a9c5a49cd721bcf559#file-block-boat-captain-css-grid-layout-php

The code isn’t very different from the first example. Only the classes have changed. Here’s the CSS for the grid layout using mobile first design:

https://gist.github.com/vfontjr/8282ff38fcd391a9c5a49cd721bcf559#file-css-grid-styles-mobile-first-css

There you have it! I hope you’ve found this to be useful.