Gutenberg has changed the way users create content within WordPress, and the way developers build WordPress plugins and themes. In this tutorial you’re going to learn how you can create custom blocks for Gutenberg.
Video: Custom Blocks for Gutenberg
A Quick Introduction to Gutenberg
Gutenberg is a totally new way for people to create content for their WordPress sites. The classic editor hasn’t changed much since WordPress was created back in 2003, and while it has always been fine for creating text-heavy blog posts, it’s not ideal for today’s media-rich websites with more complex layouts. Gutenberg is WordPress’ own response to the page builder plugins used by so many websites nowadays.
At Tuts+ we have a learning guide to introduce you to Gutenberg: An Introduction to WordPress Gutenberg, plus this simple quick start video:
In addition to these resources we have a number of courses to get you started.
Coding Blocks for WordPress Gutenberg
Building Gutenberg Template Layouts Without JavaScript
Gutenberg Plugins for WordPress
Lastly, take a look at these Gutenberg-specific themes if you’re interested in seeing what other developers are doing with it:
Methods for Creating a Custom Block
When it comes to creating custom blocks for Gutenberg you basically have two options:
- Code it from scratch
- Use a plugin
The first of these is logically the most difficult; it requires more coding knowledge as you have to register your blocks and customise them via JavaScript.
In this tutorial we’re going to take the easier route and use a plugin. The advantages of using a plugin are that we can build blocks using a visual interface, and that we don’t need to worry about registering the blocks with JavaScript. In fact, we won’t need to write any JavaScript code at all.
Plugins for Building Gutenberg Blocks
Let’s look at the plugin options we have available to us.
Block Lab
This is actually the one we’re going to use. It’s free, and perfect for our needs.
Lazy Blocks
Whilst I haven’t actually worked with this plugin yet, its reviews and ratings are very solid and suggest it’s a good option too.
Creating a Simple Block
Begin by downloading and installing the Block Lab plugin. You can find it from within your WP admin, under Add New Plugin. A new set of menu items will be added to your WP admin:
As we’re using the free version of the plugin we need only a couple of these new menu items. Click on Add New.
What Are We Creating?
We’re going to build a small CTA (Call to Action) block. It will have a title, a description, a button, and some helper text. We’ll also need some fields to allow the user to change the color of our CTA, to add a border if they want, and also add a background. Lastly we’ll create a toggle to allow users to choose whether or not to display the helper text.
So, we give our block a title (“CTA”) which will immediately assign it an ID (slug) which we’ll need later. We then state what kind of block it will be. We’ll keep ours as a common block.
We can then add keywords. These are used to find blocks when the user is creating a page layout. Hit Publish and we’ll move onto the next step where we add block templates.
There are two parts to adding a block template. There’s what’s displayed in the backend editor, and what’s shown on the frontend. For the frontend aspect of this we’ll need to write some HTML code which will output our block contents the way we want. We’ll also need to slot some PHP functions into the markup to pull the actual content in.
Begin by Adding a Blocks Folder
In the root of your currently active theme you’ll need to add a folder called “blocks”. We’ll add our new template files to this folder. And if you forget where these files are supposed to go, you can see the path referenced in the screenshot above. Our first file will be called “block-cta.php”.
With that done we can now start adding fields which the user will use to populate the block. Here you’ll see I’m adding Title, which generates a handle of the same name. We’ll need the handle in order to output the contents into our template.
This part can take a while–so begin adding all the fields you need, giving them names, types, default values, whether they’ll be present in the Editor or the Inspector (the sidebar), and whatever else you think they need. Watch the video above to see me walk through this process.
Here are all the fields I end up with:
With that saved, we can already go to a page and add our CTA block:
Here’s what our block editor looks like, with all the fields we added:
We can fill out these fields already, though nothing will be displayed in the backend because we haven’t yet built a template.
Rendering to the Backend and Frontend
Here’s the chunk of code I put together to hold the block content and output the values entered in the fields:
1 |
<div class="custom-block-cta" style="border-color: <?php block_field('border-color'); ?>; background: <?php block_field('background-color'); ?>"> |
2 |
<h3><?php block_field('title'); ?></h3> |
3 |
|
4 |
<?php block_field('description'); ?> |
5 |
|
6 |
<a href="<?php block_field('url'); ?>" class="custom-button"><?php block_field('button-text'); ?></a> |
7 |
|
8 |
<?php
|
9 |
if (block_value('display-button-helper') == 'YES') { |
10 |
echo '<p class="button-helper">'. block_value('button-helper') .'</p>'; |
11 |
}
|
12 |
?>
|
13 |
</div>
|
It’s quite self-explanatory. There’s a container div, then an <h3> heading to hold the title. The description is outputted, as is the button. Then there’s a condition to determine whether or not to display the helper text. Each bit of data is output using the block_field() function.
We can add styling too, by creating a subfolder in our blocks folder. Call it “css”, then add another file: block-cta.css and place your styles within it.
These are the styles I used for this demo:
1 |
.custom-block-cta { |
2 |
border: 1px solid; |
3 |
padding: 2rem; |
4 |
text-align: center; |
5 |
border-radius: 10px; |
6 |
}
|
7 |
|
8 |
.custom-button { |
9 |
display: inline-block; |
10 |
background: #2a8b2e; |
11 |
padding: .25rem 1rem; |
12 |
border-radius: 3px; |
13 |
color: #fff !important; |
14 |
text-decoration: none !important; |
15 |
}
|
16 |
|
17 |
.button-helper { |
18 |
font-size: 85%; |
19 |
opacity: .75; |
20 |
font-style: italic; |
21 |
}
|
The block, when rendered to the frontend, looks like this now:
The same styles are applied to the backend editor too:
Conclusion
This tutorial has given you a good idea of what’s needed to create your own Gutenberg blocks. Hopefully you can see a world of potential opening up in front of you! Gutenberg blocks are a really useful way of designing and reusing chunks of content—I look forward to seeing what you create with them!
Learn more in my two-hour WordPress tutorial for beginners, which takes you through everything from installing WordPress to managing users and moving a WordPress site. There's even a video on using WordPress Gutenberg too.
Related Links
