The new WordPress editor (codenamed Gutenberg) is due for release in version 5.0. Now is the perfect time to get to grips with it before it lands in WordPress core.
I'll show you how to work with the block API and create your very own content blocks which you can use to build out your posts and pages.
There isn't an exact date yet for when WordPress 5.0 will be released, but it should be some time within the next few months. Until then, Gutenberg is available as a standalone plugin.
I'd highly recommend trying out the new Gutenberg editor if you haven't already. It's very easy to install directly from your WordPress admin. However, because this is still a beta version of the new editor, it's not recommended that you use it on production sites just yet. Keep it for local development sites only for now.
Also, having Gutenberg installed is key if you want to follow along with this tutorial. That way, you can experiment with creating your own custom blocks. Development of the new editor has been rapidly picking up pace over the last few months, with several releases already so far in 2018. The latest version of Gutenberg is currently 2.7.0 at the time of writing.
With each release, new features are added, and the editor interface is constantly improved based on user feedback. It's starting to look and feel much slicker than previous versions. Also, lots of bugs have been fixed, making the editor much more robust.
Gutenberg provides a new way of building post content by way of "blocks", which can be stacked on top of each other to form a complete page. Each individual block exists independently from other blocks and can contain almost any markup, styles, and JavaScript you want.
Throughout this tutorial, we'll cover all you need to know about the block API so you can start creating your own custom blocks right away. Once you've mastered the fundamentals, creating more complex blocks is easier than you might think!
The Gutenberg project is big news for WordPress for another important reason. It's built on top of React. That's right, for the first time in WordPress, React will be included in core! This is great news for theme and plugin developers as React can easily be added to any page by leveraging the React and ReactDOM libraries included with WordPress core.
Pretty soon you'll be able to create UI components for all your WordPress projects directly in React. Previously, if you wanted to use React and ReactDOM libraries, you had to include them manually. Having them in core makes it much more convenient.
Just think about how awesome it would be to create a plugin options screen entirely in React! Or how about some cool advanced customizer controls? These new tools are going to give developers a lot of freedom and flexibility to create some great interactive user interfaces.
I anticipate that WordPress development over the next couple of years is going to be very interesting and a lot of fun too!
What's a Block Again?
The concept of blocks in the new editor is a real shift change from the current TinyMCE-based editor, so let's take a closer look at what a block is before we dive into the block API. Think of blocks as black boxes, each containing a bunch of markup, styles, and JavaScript all wrapped up in a convenient entity called a "block".
When a block is added to the editor, it displays a preview of what it will look like on the front end. Almost all blocks have settings to further customize their appearance and/or behavior.
Some of the blocks available by default in the new editor are:
- Paragraph
- Gallery
- List
- Quote
- Code
- Table
- Button
- Columns
This gives you an idea of the sort of content you can add to the editor using blocks included with the new editor. All these block types are useful but fairly basic, so expect plenty of plugins to start appearing with much more comprehensive blocks for adding almost any type of content you can think of.
You might have already thought of some content blocks that you need for your own projects. If none of these are available in Gutenberg, they're probably good candidates for creating your own custom block.
I'd recommend trying out the code presented in this tutorial series as it's the best way to learn how to create your own blocks using the block API. By all means read through the tutorial first to get to grips with how the block API works, but do come back and try out some of the code yourself and start creating some blocks!
Prerequisites
This is a medium to advanced level tutorial series, so it's assumed you're not new to WordPress development. To get the most out of this series, you should have at least a working knowledge of the following:
- JavaScript (ES6+)
- React (and ReactDom)
- JSX
- Command line
- Node/NPM
- PHP
- WordPress plugin/theme development
- Local WordPress development environment
If you need to brush up on any of these topics, it may be a good idea to do so before proceeding. I'll explain concepts as we go along, but it's outside the scope of the tutorial to explain every small detail.
It's common practice to create custom blocks in WordPress using JSX, but this is by no means required. If you're used to developing React components in vanilla JavaScript, you can do so in WordPress too. The choice is entirely yours. However, most of the block code you'll encounter will be written in JSX (including this tutorial), so you'll find it easier to understand concepts if you're using JSX too.
Gutenberg: Still a Work in Progress
The Gutenberg project is still very much evolving, so some things may be subject to change even by the time you read this tutorial. This could include changes to the editor interface, new core components, etc.
However, the new editor is pretty stable now, and the recently added features such as nested blocks and drag/drop reordering are quite exciting. Even if some of the minor details of how you implement blocks may change, the important thing to remember is the overall concept of blocks and how you can use them to create any type of content.
If you get stuck, I'd recommend taking a look at the official Gutenberg handbook, which is kept up to date with the latest changes. Also check out the Gutenberg project on GitHub to inspect the source code and log any issues you may come across.
This will only help the project become stronger the more people test it. This is another great reason to start developing blocks now, before they are officially a part of WordPress!
Environment Setup
To follow along with the code in this tutorial, you'll need the following:
- a local development environment
- the latest version of WordPress
- Gutenberg standalone plugin
- a code editor
If you don't already have a local development environment set up then you can use something like Local by Flywheel or DesktopServer as they both have free versions available and support multiple operating systems.
Make sure you're running the latest versions of WordPress and the Gutenberg plugin to be sure you're using all the latest features. Also, there are some great code editors out there, so if you haven't already got one installed then take a look at free editors such as Visual Studio Code or Atom, which should be more than sufficient.
To create new blocks easily, we'll be using a relatively new toolkit called create-guten-block. It allows you to quickly spin up a new plugin containing all the setup and starter code required to create blocks. It's a zero configuration toolkit too, so it works right out of the box in a similar way to the create-react-app toolkit for scaffolding out new React apps with minimal effort. So if you've ever used create-react-app, you'll know what to expect.
Let's take a look now at how we can use this tool to create Gutenberg blocks. Open up a terminal window inside your plugin folder (/wp-content/plugins/) for your local development site and enter the following:
1 |
npx create-guten-block my-custom-block |
2 |
cd my-custom-block
|
3 |
npm start |
(Note: npm v5.2+ is required to use the npx command.)
After a few minutes, a new plugin will be created inside a folder named my-custom-block containing all the files and tooling needed to create blocks using React! Not bad, eh?
The name of the plugin in the WordPress admin will be my-custom-block - CGB Gutenberg Block Plugin. Go ahead and activate it.
The plugin creates a new block which is available for us to use in the Gutenberg editor. To test our new block, navigate to the post editor and click on the placeholder text labeled Write your story.
Next, hit the / key to display a pop-up box we can use to search all available blocks.
Note: there are other ways to search for a block, but I like using / to display the search block window pretty quickly and conveniently. But use the method that you feel most comfortable with.
With the search box open, start typing my-custom-block and select my-custom-block - CGB Block. This will display our custom block inside the editor window.
At the moment it's just a boilerplate block, which doesn't really do anything other than displaying placeholder text inside a colored box. However, it does highlight one interesting aspect of creating blocks.
Click View Post to see how the post will look to site visitors.
As you can see, both the content and the styles of the rendered block are different on the front end and back end. This also applies to JavaScript code, which can be different for the front end too.
The reason for the difference in rendering is because when creating blocks, you're required to specifically declare separate front-end and back-end rendering functions.
That's because a lot of blocks require additional UI elements to be rendered inside the post editor to help configure block settings. As this is only relevant to the post editor, it's completely redundant when rendering the block on the front. Therefore, you specify the output that needs to be displayed on the front end in a separate rendering function.
Whilst this approach makes sense and works well, it does raise issues of code duplication. If you're not careful, you could end up with lots of duplicate definitions of content.
Where possible, it's a good idea to separate out content common to the front-end and back-end rendering functions to help reduce duplication. We'll be following this approach throughout this tutorial series.
Conclusion
In this tutorial, I introduced the concept of what a block is and why the new Gutenberg editor is going to be big news when it ships with WordPress 5.0. It's a real shift change from the current TinyMCE-based editor.
To help create blocks quickly, create-guten-block is a very useful tool that lets you create a complete plugin containing a working starter block ready for customization.
We rounded things off by seeing how to use our custom block inside the new post editor, and we discovered that rendering on the front and back end can look very different. In Gutenberg, you're not required to match the output whatsoever!
In part 2, we'll get into the specifics of the block API and how you can leverage it to create your own custom blocks.
In the meantime, check out some of our other posts about WordPress Gutenberg!
