If you’re thinking of developing anything for WordPress in 2022, ignoring Gutenberg is simply not an option. Plugins and themes all have to cooperate with Gutenberg nicely and deliver a user experience that’s consistent throughout everything a user can see in the WordPress dashboard. And especially since Gutenberg is an integral part of WordPress now – simply referred to as the block editor.
That being said, getting started with Gutenberg isn’t as straightforward. Whereas a couple of years ago you could write a quality WordPress plugin using nothing but Notepad, the process has become much tougher now.
Gutenberg uses technologies like the WordPress REST API, JavaScript, and React. Thus, new requirements for plugins and themes were necessary to work with Gutenberg.
The good news is that we’re going to talk about all that today! This post serves as a Gutenberg tutorial for beginners, who are looking to create a plugin for Gutenberg for the first time.
We focus primarily on the various aspects of creating a plugin for Gutenberg — setting up the development environment, creating a basic plugin and some nuances of working with blocks.
1. Set up your Gutenberg development environment
To start with Gutenberg development, you need some basic knowledge of JavaScript and React. Here is a tutorial on JavaScript for a WordPress developer. Further, additional packages in Gutenberg may need the use of a NodeJS package manager, npm.
You can install the latest stable version of NodeJS on Windows or MacOS using the installers on the official site. If you have a Linux server, you can either compile the source code or use the corresponding package manager (like apt and yum). For instance, if you are using Ubuntu, run the following commands on the terminal.
sudo apt update sudo apt install nodejs npm
After the installation is successful, you can run the following command to verify the version of NodeJS.
nodejs --version
After ticking those boxes, it’s a good idea to set your test WordPress website up with an instance of the current Gutenberg plugin (the standalone plugin) or even the development version of it – you can get that from GitHub.
⚠️ Note; while Gutenberg is now built into WordPress, that version isn’t the latest one. The development on Gutenberg still happens fairly separately and all that’s new gets included in the Gutenberg standalone plugin first. The actual Gutenberg version in the core is yet to receive any major update since its inclusion in WordPress 5.0. You always want to be working on the latest version of Gutenberg since it gives you a better chance of future-proofing your work and making sure that your creation will be in tune with everything that’s coming to the WordPress core later on.
On another note, if you intend to contribute to the core Gutenberg plugin, the repository has contributing guidelines on how to set up your local environment and set up changes for review.
👉 Finally, if you’re looking to adapt your existing plugins to Gutenberg, here is a detailed tutorial on how to achieve this:
part 1: How to Adapt Your Plugin for Gutenberg (Block API) and
part 2: How to Make Your Plugin Compatible With Gutenberg (Sidebar API).
In order to get started with a template plugin directory that’s already ready to cooperate with Gutenberg, you may consider using the Gutenberg boilerplate plugin. Such a solution helps you with the basic file structure so that you can focus on the content of the plugin. To use the boilerplate, download and install the plugin from here (zip). Installing and activating the boilerplate plugin activates the sample blocks, which we will explore in this tutorial. You can find the code for each block in its respective directory in the boilerplate’s plugin location.
2. Initial configuration
Just to remind you, Gutenberg introduces the concept of blocks, which are a replacement for the standard TinyMCE editor canvas. In some cases, blocks can also replace shortcodes and other additional content elements that plugins used to add to WordPress content in various ways.
If you’re interested in building for Gutenberg, the most common approach is to build a plugin that creates new blocks and makes them available to the user. This is exactly what we’re going to do in this Gutenberg tutorial.
The following sections describe the process from start to finish.
The specific plugin we’re going to build prints out a message with a certain background that is customizable. Just an example build, but you can take the principles presented here and apply them to your own, more complex plugin.
The basics of building such a plugin should be familiar. You start by creating a new directory in the plugins
directory of WordPress. In it, we’re going to place four files:
index.php
– This file contains metadata about the new Gutenberg block.block.js
– This JavaScript file registers the custom Gutenberg block.editor.css
– This file contains styles for the editor.style.css
– This file contains the styles for the front end of the block.
The first two files in the list take care of registering the block and the next two files define the visual styles of the elements of the block.
3. Registering the block
In this step of registering a block for Gutenberg, we will broadly cover two things:
- registering metadata of the plugin with the PHP engine of WordPress,
- registering the block with the React framework that Gutenberg runs on.
The index.php
file contains the enqueue assets of the block and the editor.
- First, register the custom functions through
add_action
. - Then, define the functions that list down the path of the JavaScript and CSS files for the block and editor using the
wp_enqueue_style
andwp_enqueue_script
functions.
Let us summarize this through the PHP code below:
add_action( 'enqueue_block_editor_assets', 'gb_block_01_basic_editor_assets' ); function gb_block_01_basic_editor_assets() { // Scripts. wp_enqueue_script( 'gb-block-01-basic', plugins_url( 'block.js', __FILE__ ), array( 'wp-blocks', 'wp-i18n', 'wp-element' ), filemtime( plugin_dir_path( __FILE__ ) . 'block.js' ) ); // Styles. wp_enqueue_style( 'gb-block-01-basic-editor', plugins_url( 'editor.css', __FILE__ ), array( 'wp-edit-blocks' ), filemtime( plugin_dir_path( __FILE__ ) . 'editor.css' ) ); }
This defines the resources for the basic editor. For the block, only the CSS file is needed, which is defined through the wp_enqueue_style
function.
The block.js
file describes the properties of the block in the Gutenberg editor. We define the following attributes and properties:
title
– The title of the blockicon
– An icon to display for the block; you can select any icon from this collection of dashiconscategory
– The group that the block will belong to. Examples of groups of blocks are “common,” “formatting,” “embed.”edit
– A JavaScript function that returns a DOM element. We use thewp.element.createElement
function to create a custom paragraph DOM element,p
, with custom text written in it. Gutenberg invokes this property when a user clicks the block from the editor.
( function() { var registerBlockType = wp.blocks.registerBlockType; registerBlockType( 'gb/basic-01', { title: __( 'GB Basic', 'GB' ), icon: 'shield-alt', category: 'common', edit: function( props ) { return wp.element.createElement( 'p', { className: props.className }, 'Hello World! — from the editor (01 Basic Block).' ); }, } ); })();
Similarly, you can create a save
property that is invoked when the block is selected from the front end.
In the code above, we defined the className
of the p
element with the props.className
, which will create a class name starting with wp-block
, followed by the name of the block. In the next section of this Gutenberg tutorial, we define the styles of this class.
4. Customizing the block
As discussed in the previous section, the next step in this tutorial is to define the properties of the block elements. Let us define a background color, a text color and a border.
.wp-block-gb-basic-01 { color: #000; background: mistyrose; border: 0.2rem solid red; }
In place of the CSS files, you may also add SCSS files and compile them with Node. Further, here is a tutorial on styling Gutenberg elements from CSS Tricks.
Results of your first Gutenberg tutorial
We are finally ready to test out the block that we have created. If the Gutenberg plugin is activated, head over to the + icon and check if the new block appears there.
Next, if you click on the block, you will notice that the message from above is seen, with a background color and a border from the CSS file:
Conclusion
We come to the end of your first Gutenberg tutorial. I hope this has been helpful. Granted, what we’ve built here is not super complex, but it should give you an idea of the basic structures when working with Gutenberg and how to plan out your next plugin.
First, we discussed the steps to set up the Gutenberg development environment. Next, we introduced a boilerplate plugin to help with further development. Then, the focus of the discussion shifted to various steps in registering and styling a new block.
I hope that this Gutenberg tutorial has helped you in creating your very first Gutenberg plugin!
If you have any questions, fire away in the comments below.
Don’t forget to join our crash course on speeding up your WordPress site. Learn more below: