Building A Custom Gutenberg Block In WordPress

Gutenberg Blocks in WordPress have been around for a while, ever since the builder was released on the WordPress platform. Its ease of use with dragging and dropping blocks on a white canvas has shown it has a lot of potential for building websites in the future similar to current WordPress website builders such as Elementor and Divi.

In this article, I'll be sharing how you can create a simple Gutenberg block that displays what I call a Blurb (a UI component that consists of an icon/image, title text, summary text, body text).

There are 2 parts to a Gutenberg block, the first part is the PHP part and the second part is the React part. These 2 parts must be present to enable your block to work properly.

To keep things tidy and organized, it will be best we put all of our files into a folder or plugin structure. So create a folder in your plugins folder and rename it as blurb, then create a file within your blurb folder and rename it as blurb.php like so:

Next, you'll need to initialize your plugin repo using NPM so you can import Node packages you might need for development purposes. So, open your terminal and type the following command:

npm init -y        

This will create a package.json file for you like so:

Next, we will create 2 new folders called "src" and "build" where our JSX and compiled ES6 files will be located respectively like so:

Now we're ready to start coding!!!

Step 1 (PHP)

In your plugin file (blurb.php), type in your plugin info like so:

<?php
/**
 * Plugin Name: Blurb
 * Description: A custom Gutenberg block.
 * Author:      Chigozie Orunta
 */        

Next, we'll create a function called "register_blurb". This is where we will define our custom Gutenberg block by using the "register_block_type" function.

function register_blurb() {
    register_block_type( 'chigozieorunta/blurb', array(
        'editor_script' => 'blurb'
    ) );
}        

The register_block_type function in our case will take 2 arguments, namely the block type which contains your namespace and the name of your block (which in my case I have named chigozieorunta/blurb) and an array containing the handle of the editor_script to be used when the blurb block is loaded or activated (which in my case I have named blurb).

Then, we'll use the "init" hook to help us run the callback function we just created once WordPress is done loading (just before any headers are sent out) like so:

add_action( 'init', 'register_blurb' );        

With the above added, your plugin file should now look like this:

<?php
/**
 * Plugin Name: Blurb
 * Description: A custom Gutenberg block.
 * Author:      Chigozie Orunta
 */

add_action( 'init', 'register_blurb' );

function register_blurb() {
    register_block_type( 'chigozieorunta/blurb', array(
        'editor_script' => 'blurb'
    ) );
}        

Next, we'll register the handle (called blurb) to the script editor I mentioned earlier like so:

wp_register_script( 'blurb', plugin_dir_url( __FILE__ ) . 'build/index.js', array( 'wp-blocks', 'wp-editor' ) );        

Please note that the above function simply attempts to import wp-blocks and wp-editor JS dependencies and then loads the compiled ES5 build of our JSX file found within the build folder we created at the beginning of this article.

When you add the above code to our plugin file, you'll have:

<?php
/**
 * Plugin Name: Blurb
 * Description: A custom Gutenberg block.
 * Author:      Chigozie Orunta
 */

add_action( 'init', 'register_blurb' );

function register_blurb() {

    wp_register_script( 'blurb', plugin_dir_url( __FILE__ ) . 'build/index.js', array( 'wp-blocks', 'wp-editor' ) );

    register_block_type( 'chigozieorunta/blurb', array(
        'editor_script' => 'blurb'
    ) );
}        

Step 2 (React)

Now let's move onto the second part of our Gutenberg block, which is the React JSX component you'll create. This is where a lot of the magic happens.

To start, create an index.js file in your "src" folder and type in the following:

const { registerBlockType } = wp.blocks;

const edit = () => {
    return '';
}

const save = () => {
    return '';
}

registerBlockType('chigozieorunta/blurb', {
    title: 'Blurb',
    description: 'Blurb Component',
    icon: 'format-image',
    category: 'layout',
    attributes: {},
    edit,
    save,
});        

To help you understand what's going on here, I'll break it down a little bit more.

The first line contains what we call an object destructuring statement like so:

const { registerBlockType } = wp.blocks;        

This is a very familiar concept in ES6 JavaScript, it simply gives you a way of accessing the properties of an object, so you don't have to keep typing it all over the place within your code. If we didn't do it this way, then we'd have to call the registerBlockType function like so:

wp.blocks.registerBlockType('chigozieorunta/blurb', {
    title: 'Blurb',
    description: 'Blurb Component',
    icon: 'format-image',
    category: 'layout',
    attributes: {},
    edit,
    save,
});        

But by destructuring it, we can simply call the registerBlockType on its own with ease (which is best practice nowadays).

The next sections which are the "edit" and "save" functions (or functional components) provide a way for us to return JSX. The JSX is what renders on our Block Editor when a user selects our custom block.

const edit = () => {
    return '';
}

const save = () => {
    return '';
}        

The main difference between the two is that the "edit" provides us a place to define methods or behaviors (functions) for modifying the look and feel of the block during use, while the "save" is responsible for the final rendering we see on the block editor and the front-end.

The last part of the block is where we call the registerBlockType function. This takes in two arguments namely the block type and an object containing your block info (title, description, icon, category, attributes, edit, save).

Step 3 - Components (Edit & Save)