How to Create a Custom Block Using Advanced Custom Fields

Say what you will about Gutenberg, it’s not going anywhere. We are about six months into this now, and I will admit that I have been installing the Classic Editor plugin on the sites that I work on. Not because I have some deep-seeded hatred of Gutenberg. Sure, I find it lacking in a variety of areas, but I have been eagerly anticipating the release of ACF Blocks. This greatly simplifies the creation of a custom block.

I know, I know, I write about Advanced Custom Fields all the time. But, to be fair, it has made my life as a developer so much easier. I figured there was a good chance that their answer to Gutenberg would be a good one.

And I was correct. Turns outs, creating custom blocks with ACF is simple and actually fixes a lot of the issues I had with Gutenberg in the first place.

Setting Up a Custom Block

If you are familiar at all with creating custom post types, then creating a block with ACF will feel fairly natural to you. All you need to do to create a custom block is place the following code into your functions.php.

add_action('acf/init', 'register_custom_banner');
function register_custom_banner() {

   if(function_exists('acf_register_block_type')) {
      acf_register_block_type(array(
         'name' => 'your-custom-block',
         'title' => __('Your Custom Block'),
         'description' => __('A custom block.'),
         'render_template' => 'block.php',
         'enqueue_style' => 'block.css',
         'category' => 'layout',
         'icon' => 'format-image',
         'keywords' => array('custom', 'block'),
      ));
   }
}

As you can see, there are eight parameters to set for your custom block. Let’s talk a little bit about what’s going on here:

• The name is basically an  for your custom block
• The title is what shows up in the admin area when you are selecting a block to use.
• The description is just like it sounds, it’s a description of your custom block.
• The render_template references a php file that will act as the template for your custom block, not unlike a page template file. It will contain the code that will render the block both on the front-end and in the admin area.
• The enqueue_style acts just like enqueuing a stylesheet in your theme’s functions.php file. Like the template file, it will contain the CSS needed to render the block styles on the front-end as well as the admin area.
• The category will determine in which category your block will be placed.
• The icon is…well…an icon that will show above the title of your block. You can use WordPress dashicons for this. One thing of note is to remove the dashicons- from the beginning when placing one into the code above. Not sure why, but it only works if you remove that.
• The keywords are an array of words that will help identify your block within the block search in the admin area.

So, from these parameters, we can see that in addition to the code above, we are going to need two other files. First, a php file that will act as a template for the block. Second, a stylesheet that will hold the styles for the block. It’s important to remember that these will effect not just the front-end, but also help to render the block in the admin area.

Building a Custom Block

For the sake of this post, let’s say that we want to create a “Features” block. This block will show some features that we want to highlight on our website. Let’s modify the above code to look like this:

add_action('acf/init', 'register_custom_banner');
function register_custom_banner() {

   if(function_exists('acf_register_block_type')) {
      acf_register_block_type(array(
         'name' => 'features',
         'title' => __('Features'),
         'description' => __('A block that shows features'),
         'render_template' => 'features.php',
         'enqueue_style' => 'features.css',
         'category' => 'layout',
         'icon' => 'images-alt',
         'keywords' => array('features'),
      ));
   }
}

With that created, we can now create some custom fields to place inside of this block. For this example, we will create a repeater field for our features and assign them to the block we created with the code above. Something like this:

This repeater field will have two subfields. One for an image and another for a short description of the feature. We will use these subfields in the template file we are about to create for our block.

Speaking of which, let’s create our features.php file and place the following code inside:

<?php if(have_rows('features')): ?>
<div class="features">
   <?php while(have_rows('features')): the_row(); ?>
   <div class="feature">
      <?php if(get_sub_field('image')) { ?>
      <img src="<?php the_sub_field('image'); ?>" alt="<?php the_title(); ?>" />
      <?php } ?>
      <?php if(get_sub_field('text')) { ?>
      <p><?php the_sub_field('text'); ?></p>
      <?php } ?>
   </div>
   <?php endwhile; ?>
</div>
<?php endif; ?>

Now, we need some CSS to make this look nice. We will place this in our new stylesheet that we are referencing in our block code:

.features {
   margin: 0 auto 25px;
}

.features:after {
   visibility: hidden;
   display: block;
   font-size: 0;
   content: " ";
   clear: both;
   height: 0;
}

.features .feature {
   width: 30%;
   margin-right: 2%;
   vertical-align: top;
   text-align: center;
   display: inline-block;
}

.features .feature:last-of-type {
   margin-right: 0;
}

.features .feature img {
   display: inline-block;
   margin-bottom: 20px;
   max-width: 100%;
   height: auto;
}

That’s it! Well, at least as far as code is concerned. Now, we need to add this block to our page and fill out the custom fields.

When we go to the editor, we will notice that our lovely new block is now listed in with the rest of the native blocks:

You’ll notice that nothing shows up when we first add the block. Don’t be alarmed, we just need to click on the pencil icon. Once we do, we will see the ever familiar custom fields. Here, we can add our images and text for our features. For this example, we will enter three.

Here’s what things will look once we have our fields filled out:

Believe it or not, that’s all we need. On the front end of our page, we should see our features in all their glory.

Not Too Bad, Right?

If you have been holding out on Gutenberg up until now, I totally understand. The learning curve has been steep in some cases (especially when it came to creating custom blocks pre-ACF) and there are still many flaws both perceived and actual. However, I think that ACF Blocks definitely bridges some of these gaps. I believe it’s a game changer.