Neither the constant growth in the amount of websites that choose WordPress nor its dominant position in the market have made the WordPress development community relax. WordPress is going to change a lot in a very short time. And the biggest change in WordPress is called Gutenberg.
In this article I’m going to talk about Gutenberg and I’m going to show you how to get involved in its development by creating your first block, a concept that you will certainly have to master if you plan to continue earning a living with WordPress for years to come. Let’s get started!
What is Gutenberg?
Gutenberg is the new content editor for WordPress. But it’s much more than that. Gutenberg will change the way users and developers work with WordPress.
So far you’ve used WordPress‘ editor as if it were a Microsoft Word document. Well, this is about to change as the concept of block appears on the scene. Now your WordPress content will be composed of blocks—you’ll have blocks for paragraphs, images, headers, quotes, and more. In addition, the developer community will go crazy by creating plugins that add new custom blocks.
If you want a first glimpse of Gutenberg’s look, don’t miss the following video where Matías Ventura, the lead developer of Gutenberg, demoed its main features during the past WordCamp US 2017:
Also, keep in mind that Gutenberg won’t only be the editor in WordPress—in future development iterations, the block concept will replace other familiar concepts in WordPress such as widgets and menus. Soon WordPress will be all blocks. And that’s why I’m interested in teaching you how to create a basic block today.
Install and Activate Gutenberg
It’s said that Gutenberg will be ready to be included in WordPress version 5.0 by April 2018. But I think we’re gonna have to wait a little longer until Gutenberg ends up inside WordPress.
Right now if you want to try Gutenberg you will have to install a plugin. But be careful, I don’t recommend you to do it in your production WordPress installation, since it’s still under development and you can break things. Try it in a test installation instead.
Just install the Gutenberg plugin, activate it, and go to edit a post or page. By the way, I’d love to hear your opinion after testing it, as there’s been a lot of controversy with all this ?
Let’s Create a New Block for Gutenberg
Now that you know what Gutenberg is, let’s get our hands dirty and code some stuff, shall we? To do this, we are going to create a new block for Gutenberg that allows us to add a customer testimonial on our website. The testimonial will include a photo of the person, his or her name and position, as well as the text of the testimonial itself. The final result we want will look like this:
Let’s make it work!
Creation of The Plugin and Its File Structure
First of all we will create a plugin for WordPress that includes the necessary files to have a new block in Gutenberg. To do this, create a structure of files and folders like the following:
Here’s what you should know about these files:
block/testomonial/index.phpis responsible for enqueueing the files that define the block and displaying it in both the backend and the WordPress frontend.
block/testimonial/block.jsdefines the testimonial block itself and its behavior when editing and saving it. It’s the most important “Gutenberg-related” file in regarding the block.
block/testimonial/editor.csscontains CSS rules for styling the blog in the Gutenberg editor.
block/testimonial/style.csscontains CSS rules for styling the blog in the frontend, when a user accesses your site and views the final result.
nelio-testimonial-block.phpis the plugin‘s main file, where you define the headers needed to describe the plugin and include the previous
index.phpfile. If you’ve ever created a WordPress plugin, you’re already familiar with it. You can see it here.
You’ll find all the code of the testimonial block in GitHub.
Enqueue the Necessary Files
block/testomonial/index.php so that it looks as follows (see it in GitHub):
Note that we basically use two hooks:
enqueue_block_assets. The first hook is for including the files we use within the Gutenberg editor:
editor.css. It’s also worth noting that
block.js file has some dependencies (
wp-element), which are necessary if you want to create a block like ours and internationalize it. The second hook simply enqueues the frontend styles:
Register The New Block
Now let’s take a closer look at
block.js (link to the file in GitHub). First of all, we have to register the new testimonial block, which can be easily done by using Gutenberg’s
That’s a lot of code, isn’t it? But don’t panic, I”m gonna explain it step by step. First we name the block using a unique, internal identifier. In our case, this name is
'nelio/testimonial-block'. Then, we simply pass an object with all the relevant properties of the block. For instance, there’s a title (line 10), an icon (line 13), a block category (line 16), and some extra attributes (lines 19 to 47). Easy, right? ?
Attributes are the characteristics that the block will contain. In our case, the testimonial block will have the following:
- name: name of the person who writes the testimonial.
- position: job of that person.
- testimonial: the text of the testimonial.
- mediaID: ID of the image in the WordPress media library.
- mediaURL: URL of the image of the person.
- alignment: arrangement of the text in the testimonial.
One important thing to keep in mind is the following: any attribute that has an HTML element associated with it needs a unique selector, or Gutenberg will give you an error when opening the content. Thus, if for example we have several attributes that are associated with
<p> tags inside the block, we must have a different selector for each one (you can do it with different CSS class names).
Finally we have the editing and saving functions of the block. Let’s take a closer look at them both!
The edit Method
This is where the good stuff starts. The
edit method allows you to get the block ready for editing within Gutenberg. Basically, this method returns a React component formed by all the components that we want to appear in the editor. It looks like this:
It looks very complicated, but trust me, it isn’t—they’re only a bunch of React components. Essentially, we create the HTML structure by nesting elements with the function
el(). For example, if you look at lines 79 to 91, you will see that we define the
<p> tag containing the position of the person making the testimonial. We define the class of the element (
nelio-testimonial-position), a placeholder to show (Position, which is translatable), the value of the element (which we take from the previously-defined block attributes), and the
onFocus functions (to update the value of the attribute and control its focus). This pattern repeats over and over again.
There are, however, some additional peculiarities. For instance, there’s a button to open the image selector of the media library on lines 37 to 47. This uses
blocks.MediaUpload, a reusable component of Gutenberg himself. In lines 22 to 30 we also reuse another another reusable component: the bar where you can change the alignment of the text.
The save Method
save method is in charge of taking the information of the block and preparing it to save it in the database. It’s a lot easier than the
edit method and looks like the following:
Notice that we built a
div element that contains two more
divs inside. The first has the image of the testimonial and the second the three paragraphs with the text of the testimonial, the name of the person who says the testimonial, and his position.
Styling the Block
If we do nothing else, the result in the editor is not very pretty (but, hey, it works!):
which looks as follows when we add some real data:
And if we publish the post, this is what our visitors see:
To improve the way this block looks and make it more user friendly we need to add some styles. Remember those files we enqueued at the beginning? Exactly, we’re talking about the
style.css files! Well, it’s time to tweak them so that things look beautiful.
After a few minutes (you can view the final result of both files in GitHub), the block in Gutenberg finally looks like this:
and this is how it looks in the frontend:
Creating a new block in Gutenberg can be complicated, but it’s easier than expected if you go step by step. Once you’ve encoded the basic stuff, you only need to work with three files, basically.
The other two important files are those that define the styles of both the editor and the frontend:
style.css. You have already seen that a little bit of CSS can give a radical change to the final result. I encourage you to test the code and improve it.
Before I finish, let me leave you with a list of interesting resources in case you want to learn more about Gutenberg. Remember that Gutenberg will arrive soon, and we should be ready for it!
- The Gutenberg handbook. The resource par excellence. Perfect as a reference.
- Zac Gordon’s Gutenberg development course. If you are one of those who prefer a step-by-step course, this is the most complete one you will find to date.
- Ahmad Awais Gutenberg boilerplate. If you want to start developing your blocks, here are some basic examples from Ahmad Awais.
- Gutenberg examples on Github. More examples of block development for Gutenberg.
- Gutenberg design basics. If you are a designer, don’t miss this post by Tammie Lister, one of Gutenberg’s lead designers.
- Organic Themes tutorial. An incredible tutorial I used to create this one. I highly recommend it!
- Gutenberg News. If you don’t want to miss any news about Gutenberg, you should follow this news website.