April 24, 2019 in Wordpress

Gutenberg Blocks – Understanding the Basics

Let’s take a look at the Gutenberg Block in its simplest form to understand how a block works, and how can we create our own blocks.

Gradually we will move on to understand more advanced stuff to make more interesting blocks. (Editable blocks, Toolbars, Options, etc.)

WordPress has many inbuilt libraries that allow us to do different things while building Gutenberg Blocks. The one we are interested in at the moment is @wordpress/blocks (this provides utilities needed for registering and building blocks.)

We know that Gutenberg Blocks are simply JavaScript files, and to make them available in WordPress we need to register and enqueue them using the wp_register_script function. (You can read more about in the article creating your own Gutenberg boilerplate)

wp_register_script(
    'gutenberg-boilerplate-block-js',
     plugins_url( '/dist/blocks.build.js', dirname( __FILE__ ) ), 
     array( 'wp-blocks' ), 
     filemtime( plugin_dir_path( __DIR__ ) . 'dist/blocks.build.js' ), 
     true 
);

Notice the array of dependencies. We are adding wp-blocks as a dependency. WordPress make these dependencies part of the global window object, making it easier for us to use the utilities provided by this library or module (whatever you like to call them) in the blocks we are creating.

You can add other inbuilt libraries as dependencies to this array, and WordPress make them all available to us through window object. For example, you can add internationalisation library like this: array( 'wp-blocks', 'wp-i18n' )

Now that we have wp-blocks available to us, we can start writing JavaScript code for our custom block. wp-blocks comes with lots of functions, but the only one we are interested in here is registerBlockTypemethod.

Knowing that wp-blocks is available to us as part of the global window object, we do not need to import it in our block’s JavaScript file. It’s already available to us. The only thing we need to do here is destructuring the registerBlockType method, and store it in a const.

const { registerBlockType } = wp.blocks; 

registerBlcokType is a function that take two parameters, a string for Block Name and an object for Block Configuration.

Block Name [String]
The name for a block is a unique string that identifies a block. Names have to be structured as namespace/block-name, where namespace is the name of your plugin or theme.

A block name can only contain lowercase alphanumeric characters and dashes and must begin with a letter.

const { registerBlockType } = wp.blocks; 

registerBlockType( 
    //Block name (namespace/block-name)
    'gutenberg-boilerplate/block-boilerplate-block', 

    { //Configuration Object }
);

Block Configuration [Object]
A block requires a few properties to be specified before it can be registered successfully. These properties are defined through a configuration object.

We will look at the few required configurations in this article, and keep exploring the rest of them in other articles of this series.

Let’s start by adding a few properties that will make our block available in the list of blocks in Gutenberg editor.

const { registerBlockType } = wp.blocks; 

registerBlockType( 
    'gutenberg-boilerplate/block-boilerplate-block', 

    {
        title: 'Boilerplate Block', 
        icon: 'marker', 
        category: 'common', 
        keywords: [
            'Boilerplate Block',
            'boilerplate-block',
        ],
    } 
);

These properties are self explanatory, they add information about our block that makes it available in the list of blocks in Gutenberg editor.

Only Title and Category are mandatory properties, other properties are for adding additional information to make it easier to search the block.

• Title: Title of Block (can be any string).
• Description: A short description of the block. It will be shown in Block Inspector.
• Icon: You can choose an Icon from WordPress’ Dashicons or you can use an SVG to add your own Icon.
• Category: Categories are used to group the blocks to make them easier to locate. WordPress comes with a few inbuilt categories (common, formatting, layouts, widgets, embed), and we can also create our own categories.
• Keywords: An array of keywords, these keywords are aliases of block title and can be used to search the block.

There are many other optional properties available, you can read about them in the Gutenberg’s official documentation. I will be covering other properties in different articles as needed.

Last piece we need to add is two functions save and edit

Edit function holds the code for your block while you are editing a block in the Gutenberg Editor. i.e. adding or editing the content of a block.

Save function holds the code that build the preview of block in Gutenberg editor and also on frontend.

const { registerBlockType } = wp.blocks; 

registerBlockType( 'gutenberg-boilerplate/block-boilerplate-block', {

    title: 'Boilerplate Block',
    icon: 'marker', 
    category: 'common', 
    keywords: [
        'Boilerplate Block',
        'boilerplate-block',
    ],

    edit: ( props ) => {
        return (
            <div className={ props.className }>
                <p>— Hello from the backend.</p>
            </div>
        );
    },

    save: ( props ) => {
        return (
            <div>
                <p>— Hello from the backend.</p>
            </div>
        );
    },
} );

HTML code we are writing in return() is actually JSX, which allow us to write code which looks like HTML. This code is converted into JavaScript by Babel.

These functions also receive few attributes by default, for example props.className used in the above example.

You can read about these attributes in the Gutenberg’s official documentation. I will be covering them in separate articles with relevant examples.

We have learned how to build our own Block in Gutenberg, but so far this is a static block with a hardcoded HTML output. We do not have any option to add our own content to the block, this do not add much fun while practicing. Let’s explore how to make an editable block in the next part of this series.