How to Create Your First WordPress Block Gutenberg

In this article, we will learn a little more about one of the tools of the new WordPress editor, known as Gutenberg and available from WordPress 5.x. These are blocks, which allow you to insert content units of a specific type, within WordPress pages or posts, replacing traditional shortcodes. In this tutorial, we will create our first custom block, so that we can reuse units of content throughout different post or pages in a WordPress site .

The blocks allow you to create all kinds of content and customize various features, which are necessary for the content unit with which they work. Each block is treated separately when editing a post.

We will try to keep things simple and, therefore, this time we are going to build a block that only shows static content with a certain style. From that base, we can already get as complicated as we want

Definition of the block through a plugin

WordPress comes with a good collection of blocks ready to be used within your editor. To create new custom blocks then create the ideal would be to work within the context of a plugin.

To begin, we can see the folder structure of our plugin.

As you can see in the image, we are going to have two fundamental parts in this first block:

PHP : file my-first-block.php . This file is executed when the plugin is active. In it we will place the record of the new block inside the WordPress editor.
JavaScript : my-first-block.js . This file contains how the block will behave: where it should be displayed in the editor and how it is displayed once it is being used, etc.

Registration of the block in the plugin

Let’s see now how to create the plugin of our first block, in the file my-first-block.php . This plugin must be defined with the usual mechanisms for developing the plugins, basically indicating a function and the moment in which its execution is going to be hooked.

<? php
/ *
Plugin Name: My First Block Arsys
Description: A plugin to create a new block in Gutenberg
Author: Arsys Internet
Author URI: https://www.arsys.es/
Version: 0.0.0
* /

function my_first_block () {
wp_enqueue_script (
'my_first_block-js',
plugins_url ('my-first-block / js / my-first-block.js', dirname (__ FILE__))
);
}

add_action ('enqueue_block_editor_assets', 'my_first_block');

The first comments define the metadata of the plugin, title, description, authors, and others.

The function my_first_block () enqueues a script, necessary to define the custom block that we are going to create. To do this action we need at least one name for the script and the path where the code is located.

The function add_action () is responsible for hooking the function my_first_block (), for execution at the right time, with the hook ‘enqueue_block_editor_assets’, which is executed after the assets of the Gutenberg block system have been prepared for the interface of the editor

Definition of the block with JavaScript

All the part of the definition of the behavior of the blocks is done through JavaScript. For our block, which only shows a static content, it is not necessary to have a very large knowledge of JavaScript, not even React, the library with which Gutenberg has been built and which has starred in numerous articles in this blog.

Right away, we’ll discuss everything, but first, we want to show the complete code of our block:

var blockStyle = {
  backgroundColor: 'azure',
  color: '# 666',
  padding: '15px'
}

wp.blocks.registerBlockType ('my-first-block / my-block', {
    title: 'My first block',

    icon: 'media-spreadsheet',

    category: 'layout',

    edit: function () {
        return wp.element.createElement ('h2', {style: blockStyle}, 'This is your new block !!');
    },

    save: function () {
        return wp.element.createElement ('h2', {style: blockStyle}, 'This is the content that is saved !!');
    }
  }
)

1. We start by defining a variable of type object to store a few styles, which we will then use on our block.
2. We use the WordPress JavaScript API method called wp.blocks.registerBlockType () to register a new type of block. This function needs two parameters:
   • The name of the new block we are creating
   • An object, which can be quite complex, with the detail of properties and functionalities of the configuration of the block. Then we will comment on this object separately.

With this simple step, we could already see our block, within the WordPress editor, and we could use it perfectly, once the plugin is activated, of course.

Block configuration object

We have yet to see the part of the block configuration, which is delivered as a second parameter to the wp.blocks.registerBlockType () method of the WordPress API. This part can become very complex as our block becomes more sophisticated, but at the moment its properties are quite simple to understand.

Let’s first see the object to which we refer and then comment on its different properties and methods.

{
  title: 'My first block',
  icon: 'media-spreadsheet',
  category: 'layout',
  edit: function () {
      return wp.element.createElement ('h2', {style: blockStyle}, 'This is your new block !!');
  },
  save: function () {
      return wp.element.createElement ('h2', {style: blockStyle}, 'This is the content that is saved !!');
  }
}

• With the title property, we indicate the title of the block, which will appear in the WordPress editor so that we can identify and use it.
• The icon property is used to indicate an icon to represent this block. We can use one of the icons already defined for the WordPress administrator of the Dashicons library.
• The category property indicates in which section this block will be displayed. For when creating a new block you will find that these are organized in different categories.
• The edit () method is one of the most important. It indicates what the Gutenberg editor will show when this block has been used.
• The save () method, another fundamental one, indicates what the page has to show when representing the block.

Edit and save methods of the block definition

You will notice that the edit () method and the save () method are really very similar. The first one indicates how the block is represented when editing the page or post, within the WordPress administrator. The second one indicates how this block will actually be displayed when users consult the page or post that is being edited.

Within the edit () and save () methods we are using the WordPress API again to generate an element, with the method wp.element.createElement () . This method creates an HTML content, configured using various parameters:

• h2 indicates the label that will be used for this element.
• {style: blockStyle} is the CSS style declaration that will be applied to this element.
• The third parameter is the body of the element that is being created, which is a plain text.

As you can see, the edit () and save () methods are really traced for this particular case, since the block will be shown practically the same when editing the page as when viewing it. The only difference is the body of the H2 label, which will have a different text when viewed inside the editor and when saved to be displayed as content on the page.

When seeing this block inside the editor.

We have already created a first custom WordPress block! Maybe it has not been too complex, but we have been able to know the workflow so that you can create your own blocks in the future.