Code Your First Gutenberg Block Type

Welcome to Code Gutenberg. This is an introduction post for the new WordPress 5.0, Gutenberg update.

To begin in a simple manner, let’s make a gutenberg block type that will display a message in the wordpress post. This is just the bare basics to register a block and show a styled block on the front-end without the functionality of editing the block itself dynamically, so we won’t be able to edit the message from the back-end. We’ll get deeper in the editable fields on a later section.

On the first learning step we will keep things simple.

Block types in WordPress Gutenberg that have static content are implemented in JavaScript using the registerBlockType function. The function will specify the frame of a block, we describe how the block will behave so the editor will understand how it displays, how it will change when we edit it, and how the content is saved in the wordpress post.

Enqueuing Block Scripts

The way a block will behave is as we said implemented with javascript, you need to register the block server-side so that the code will run, so we need to enqueue your scripts. Register scripts and styles using wp_register_script and wp_register_style, then assign these as handles associated with your block using the script, style, editor_script, and editor_style block type registration settings. The editor_-prefixed handles will only be enqueued in the context of the editor, while script and style will be enqueued both in the editor and when viewing a post on the front of your site.

<?php

function gutenberg_boilerplate_block() {
    wp_register_script(
        'gutenberg-boilerplate-es5-step01',
        plugins_url( 'step-01/block.js', __FILE__ ),
        array( 'wp-blocks', 'wp-element' )
    );

    register_block_type( 'gutenberg-boilerplate-es5/hello-world-step-01', array(
        'editor_script' => 'gutenberg-boilerplate-es5-step01',
    ) );
}
add_action( 'init', 'gutenberg_boilerplate_block' );

Note the two script dependencies:

• wp-blocks includes block type registration and related functions
• wp-element includes the WordPress Element abstraction for describing the structure of your blocks

If you were to use a component from the wp-editor package, for example the RichText component, you would also need to add wp-editor to the dependency list.

Registering the Block

With the script enqueued, let’s look at the implementation of the block itself:

var el = wp.element.createElement,
    registerBlockType = wp.blocks.registerBlockType,
    blockStyle = { backgroundColor: '#900', color: '#fff', padding: '20px' };

registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-01', {
    title: 'Hello World (Step 1)',

    icon: 'universal-access-alt',

    category: 'layout',

    edit: function() {
        return el( 'p', { style: blockStyle }, 'Hello editor.' );
    },

    save: function() {
        return el( 'p', { style: blockStyle }, 'Hello saved content.' );
    },
} );

const { registerBlockType } = wp.blocks;
const blockStyle = { backgroundColor: '#900', color: '#fff', padding: '20px' };

registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-01', {
    title: 'Hello World (Step 1)',

    icon: 'universal-access-alt',

    category: 'layout',

    edit() {
        return <p style={ blockStyle }>Hello editor.</p>;
    },

    save() {
        return <p style={ blockStyle }>Hello saved content.</p>;
    },
} );

Once a block is registered, you should immediately see that it becomes available as an option in the editor inserter dialog, using values from title, icon, and category to organize its display. You can choose an icon from any included in the built-in Dashicons icon set, or provide a custom svg element.

A block name must be prefixed with a namespace specific to your plugin. This helps prevent conflicts when more than one plugin registers a block with the same name.

The edit and save functions describe the structure of your block in the context of the editor and the saved content respectively. While the difference is not obvious in this simple example, in the following sections we’ll explore how these are used to enable customization of the block in the editor preview.