This post is dedicated to a wonderful WordPress Bogota community that invited me to speak on their meetup. I’ll summarise here what we’ve learned on that meetup.
At this point, I assume that you know what Gutenberg is, you know the basics of WordPress programming and a very basic understanding of React.
You need to start with a clean and fresh WordPress installation.
In order to start developing React application, you will need to have Node JS installed on your computer and Composer. There are quite a few tutorials online on how to do it so I will not explain it in details. Once you have Node JS and composer, we will use a Gutenberg boilerplate in order to speed up the setup. It’s a set of files and setup that everyone has to do at the beginning of the development. Of course there are different approaches to developing React application, however, this is a basic tutorial and the point of it is to understand Gutenberg structure and basic elements.
I will be using Windows commands as an example with Git bash command line, however, on Mac and Linux the commands are identical and on Windows, you can use and shell simulating program.
npx create-guten-block my-block
The third part of the command will be the name of your plugin and is editable – you can name it any way you can. The documentation has examples on how to create multiple blocks in one plugin in order to avoid a growing list of WordPress plugins.
Once the command is executed you should see the following screen.
The next step is to compile the React application. Go to your plugin folder (which should be “my-block” and execute the command
Because we created a WordPress plugin with the first command line we need to go to plugins and activate the plugin. Once activated, the plugin should give you a basic block out of the box. To check it, create a new page and press the plus sign and add your block to the content.
Let’s take a look at our plugin’s file structure. The most important files are highlighted here:
To understand better how Gutenberg we have to step back a little bit and understand how any plugin works. Any WordPress plugin has a frontend and a backend. Both frontend and backend are PHP files and generate HTML based on some logic. The difference is that one generates the HTML for the admin area, the other one for the frontend website.
We then have block.js file that we’ll describe below and 2 Sass files. The boilerplate is configured well enough that the files are compiled automatically while the “npm start” command is running in the background. The reason why we have 2 different files is the same reason why we have frontend and backend. Simply “editor.scss” is responsible for styling the block in the admin area and “style.css” is responsible for styling the block on the frontend of the website. We also have a common.scss file that contains common values for both frontend and backend.
Gutenberg itself is structured in “frontend” and “backend” way as well. Open block.js file and have a look at the structure. The comments of the default boilerplate file are pretty good but let’s focus on 3 important elements that we need to understand before any further development.
This is the part where we define the block, we can see some basic descriptions of the block like the title, icon, category and keywords (for search). Feel free to play around with those values and see what the effect is on your block.
As I mentioned – the comment of the function is pretty descriptive but also pretty technical. In a nutshell, the edit function is in a way description of how we are going to process the block in the backend (WordPress admin). This is the place where we’re going to add any settings, any variables and any processing.
However, as you’ll see in lesson 2, once the things get a bit more complicated, you might need to debug some elements.
We will not dig into complex React debugging, however, here are 3 most important things to know on how to see what’s wrong with your Gutenberg block.
- In order to speed up Gutenberg core – it’s compiled and stripped of some functionality in WordPress core. That is why for any development you will need to install the Gutenberg plugin that will allow you to see your errors with details.
- When you make an error in React, HTML or SCSS structure, you will see it in your system console where you run npm start command.
- Finally, a standard browser console is your go-to to check the errors on your website. On Chrome Windows press F12 and click on “console” tab to see the errors of the current page, on Mac Chrome you’ll need to right-click on the website and click “inspect” to open the console
Create Guten Block boilerplate is a great starting point for developing your first Gutenberg block. Out of the box, it is very well configured and explained in comments. I encourage you to play around with default edit and save functions and HTML inside to see how easy it is to create a simple block.
In the next lesson we’ll make our block editable and add a setting to it.