How to Create Custom Blocks in WordPress Using the Gutenberg Boilerplate Project

The new Gutenberg editor is currently slated to join core in WordPress 4.9. This means you should be already starting to learn how to make your projects work natively in the new editor interface.

As WordPress continues to forge ahead as a dominant Content Management System (CMS), advancements such as the REST API and an increased focus on advanced JavaScript are becoming more important for developers to understand. Right now, it’s the turn of the Gutenberg editor, which has a focus on content blocks. Learning how to interact with this new tool will help keep your plugins and themes modern and up to date.

In this article, we will introduce you to the Gutenberg project and its block-based approach, then discuss the Gutenberg Boilerplate project. Finally, we will teach you how to set up your first Hello World block in five steps. Let’s jump in!

An Introduction to WordPress’ New Gutenberg Blocks

Gutenberg plugin in WordPress directory
The Gutenberg plugin is available at WordPress.org

Gutenberg is a project heavily supported by Matt Mullenweg, as the hopeful replacement for the current WordPress editor. The difference lies in how it treats content as blocks, rather than as a single long stream of content. At the time of this writing, the Gutenberg project is moving along at a rapid pace. However, it’s still quite rough (which is understandable), and has received a degree of criticism from some quarters of the community.

Through all of this it seems clear that, one way or another, WordPress will soon be embracing the idea of content blocks in a revamped editor. The idea is to arrange content into modules, ideally enabling you to have more control over your page content. To understand how content blocks work, have a look at WordPress’ widgets. These are flexible drag-and-drop pieces you can move around on your site between different sidebar areas. Gutenberg is attempting to recreate this concept within the editor as well, opening up possibilities for what you can create using only the content editor.

At the end of the day, Gutenberg is aiming to make blocks the standard way of creating and managing content in WordPress. However, this means you’ll potentially need to make a big shift in the way you approach content management in your plugins and themes.

In the following sections, we’ll introduce you to a helper plugin called Gutenberg Boilerplate, and explain how you can use it to become familiar with content block management.

Introducing the Gutenberg Boilerplate

Gutenberg boilerplate project welcome graphics
The Gutenberg Boilerplate is an add-on plugin for Gutenberg.

As Gutenberg is a young project and its approach to content is so new for WordPress developers, there’s a real need for some guidance in learning the ropes. Thankfully, Ahmad Awais has created the Gutenberg Boilerplate to help you kick-start your development with the new editor. A ‘boilerplate’ (in the software world) is designed to be a starting point or guide to help you interact with other technologies. As you can imagine, these are particularly helpful for new or complex projects, such as the Gutenberg editor.

Inside the Boilerplate, you’ll find code that makes it relatively easy to create new blocks and interact with the new Gutenberg editor. You can then take this working code, play with it, and tweak it to meet your own project’s needs. In a nutshell, you can skip straight to experimentation rather than attempting to build your own working solution from scratch.

Now that you’re familiar with Gutenberg and the Gutenberg Boilerplate, let’s get coding!

How to Create a Custom Hello World Block Using the Gutenberg Boilerplate Project (In 5 Steps)

It’s important to remember that the Gutenberg editor is brand new software and is currently under major development. Even so, its core approach to content is consistently centered around blocks.

The goal of this tutorial is to help you become familiar with this approach and get a feel for what it’s like to interact with the upcoming Gutenberg editor. Hopefully by the end, we’ll have helped you round the sharpest part of the learning curve so you’re comfortable experimenting with new possibilities.

Step 1: Install Gutenberg and Gutenberg Boilerplate

First things first, you’ll need to install both the Gutenberg editor and the Gutenberg Boilerplate on a development website. Because neither of these are ready for production, they shouldn’t be installed on a live website.

As Gutenberg itself is available in the WordPress.org Plugin Directory, you can install and activate it like any other plugin from your WordPress dashboard. When you’re ready, install the Boilerplate by following these steps:

  1. Download the Gutenberg Boilerplate .zip file.
  2. Go to your WordPress dashboard under Plugins > Add New > Upload Plugin and upload your .zip file.
  3. Click the Activate Button.

Next, open up the Gutenberg Boilerplate plugin files in a code editor such as Atom, so you can explore the options for creating custom blocks.

Step 2: Customize the Block Styles

By default, the Gutenberg Boilerplate plugin offers you four different types of blocks to work with. Make a copy of the 01-basic folder within the plugin files, and name it something like hello-world. If you open this new custom folder, you’ll see four important files:

  1. block.js
  2. editor.css
  3. index.php
  4. style.css

For now, we’re going to focus on the style.css and editor.css files, and customize the selector and colors to make them our own:

.wp-block-gb-hello-world 
color: #333333;
background: aliceblue;
border: 0.2rem solid lightblue;
padding: 2rem;

Once these styles are customized, we’ll need to go ahead and update the registration of the block in the Gutenberg editor to match our new selector and styles.

Step 3: Rename Unique Block Identifiers

To make this block unique from its source, you can rename the function it runs on in PHP to something custom. Within your new hello-world folder, open up index.php. On lines 17 and 28, update the name of your block’s function to something different:

add_action( 'enqueue_block_editor_assets', 'gb_block_hello_world_editor_assets' );

function gb_block_hello_world_editor_assets() {

You’ll want to rinse and repeat for the block_assets function too. These can be found on lines 48 and 55:

add_action( 'enqueue_block_assets', 'gb_block_hello_world_block_assets' );

function gb_block_hello_world_block_assets() {

Meanwhile, it’s also a good idea to rename your enqueued files. Here’s our line 31…

'gb-block-hello-world', // Handle.

…line 39…

'gb-block-hello-world-editor', // Handle.

…and line 58:

'gb-block-hello-world-frontend', // Handle.

All this renaming may feel a bit tedious, but it is necessary in order to make this block your own.

Step 4: Register the Block in Gutenberg

Next, we’ll go to the block.js file, where our block gets registered for use in the Gutenberg editor. Open up this file so you can customize it to our new block settings, and on line 28, update the name of your block:

registerBlockType( 'gb/hello-world'

You can also rename the block title on line 29:

title: __( 'Hello World', 'GB' )

As for the content that shows up in this block, it can be changed on lines 39 and 48:

'A custom Hello World from Torque!' // Content inside the tag.

Finally, it’s time to tell Gutenberg about the presence of your new block. Open the gutenberg-boilerplate.php file at the root folder of the Gutenberg Boilerplate plugin, and add this line towards the end:

require_once( GB_DIR . '/block/hello-world/index.php' );

At this point, your custom block should be ready to roll! Next, it’s time to test it out in the Gutenberg editor – so make sure your files are all up to date on your testing server.

Step 5: Test Your Block in the Gutenberg Editor

Searching for blocks in Gutenberg
An example of searching for blocks in Gutenberg.

In your WordPress dashboard, go to Gutenberg > New Post. Here, you can test out your custom content block! There are three steps to follow:

  1. Navigate to the Insert drop-down.
  2. Type “hello world” into the search field.
  3. Click on the new Hello World content block.

You should see the custom Hello World message you entered earlier show up in the editor:

Displaying a custom block in Gutenberg

Congratulations; you just finished creating your own custom content block in the Gutenberg editor! Going forward, we recommend keeping an eye on changes to the Gutenberg editor in the WordPress directory and the Boilerplate project on Github. From there, you can continue experimenting with the possibilities of these new content blocks.

Conclusion

WordPress continues to adapt and change with modern technologies, so the creation of the Gutenberg editor is no surprise. However, it requires developers to continue learning about new advancements, as well as updating their plugins and themes to remain compatible.

In this article, we’ve introduced you to the key concept of content blocks, and walked you through these steps to create your own:

  1. Install Gutenberg and Gutenberg Boilerplate.
  2. Find and customize the block styles.
  3. Rename and register the block in Gutenberg.
  4. Test the live version of the content block on your website.

What questions do you have about creating content blocks for the new Gutenberg editor? Share your thoughts in the comments section below!

Image credit: Mr Cup / Fabien Barral.

The post How to Create Custom Blocks in WordPress Using the Gutenberg Boilerplate Project appeared first on Torque.