gutenberg-extend-blocks.png

How to extend existing Gutenberg blocks in WordPress

  • Jürg Hunziker

This tutorial explains step by step how it's possible to extend existing Gutenberg blocks in WordPress.

The new WordPress editor (Gutenberg) comes with lots of pre built blocks (Paragraph, List, Image, etc.). Each block has its own markup which wraps the content of it. This markup is generally generic enough that it works with most of the themes. But there are cases where you would like to change the appearance of these blocks in some way.

Let's say we would like to add a spacing control to the existing image block (core/image) where we can choose between a small, medium or large margin which should be added below the image.

1. Add spacing attribute

Before we can add a custom control to the image block we need a place where we can save the chosen value. In Gutenberg this is done with block attributes.

To add a custom attribute to an existing block we can use the blocks.registerBlockType filter like this:

import assign from 'lodash.assign';
const { addFilter } = wp.hooks;
const { __ } = wp.i18n;

// Enable spacing control on the following blocks
const enableSpacingControlOnBlocks = [
    'core/image',
];

// Available spacing control options
const spacingControlOptions = [
    {
        label: __( 'None' ),
        value: '',
    },
    {
        label: __( 'Small' ),
        value: 'small',
    },
    {
        label: __( 'Medium' ),
        value: 'medium',
    },
    {
        label: __( 'Large' ),
        value: 'large',
    },
];

/**
 * Add spacing control attribute to block.
 *
 * @param {object} settings Current block settings.
 * @param {string} name Name of block.
 *
 * @returns {object} Modified block settings.
 */
const addSpacingControlAttribute = ( settings, name ) => {
    // Do nothing if it's another block than our defined ones.
    if ( ! enableSpacingControlOnBlocks.includes( name ) ) {
        return settings;
    }

    // Use Lodash's assign to gracefully handle if attributes are undefined
    settings.attributes = assign( settings.attributes, {
        spacing: {
            type: 'string',
            default: spacingControlOptions[ 0 ].value,
        },
    } );

    return settings;
};

addFilter( 'blocks.registerBlockType', 'extend-block-example/attribute/spacing', addSpacingControlAttribute );

Let me explain this code step by step:

First we need to define some variables which are used at multiple places in our example.

// Enable spacing control on the following blocks
const enableSpacingControlOnBlocks = [
    'core/image',
];

In the enableSpacingControlOnBlocks array we can list all existing blocks where the spacing control should be available. In our example we just add the core/image block.

// Available spacing control options
const spacingControlOptions = [
    {
        label: __( 'None' ),
        value: '',
    },
    {
        label: __( 'Small' ),
        value: 'small',
    },
    {
        label: __( 'Medium' ),
        value: 'medium',
    },
    {
        label: __( 'Large' ),
        value: 'large',
    },
];

The spacingControlOptions array lists all available options which can be chosen in our spacing control element.

const addSpacingControlAttribute = ( settings, name ) => {
    // Do nothing if it's another block than our defined ones.
    if ( ! enableSpacingControlOnBlocks.includes( name ) ) {
        return settings;
    }

    // Use Lodash's assign to gracefully handle if attributes are undefined
    settings.attributes = assign( settings.attributes, {
        spacing: {
            type: 'string',
            default: spacingControlOptions[ 0 ].value,
        },
    } );

    return settings;
};

This is our callback function where the custom attribute gets registered. We first check if the block is one of our defined blocks in the enableSpacingControlOnBlocks array. If that's the case we add our new attribute spacing to the already existing blocks attributes.

addFilter( 'blocks.registerBlockType', 'extend-block-example/attribute/spacing', addSpacingControlAttribute );

Last but not least we need to add this function to the blocks.registerBlockType filter.

The core/image block now has a new attribute spacing which we can use to save our chosen value.

2. Add spacing control

As a next step we need to create the spacing control element to the blocks InspectorControl.

The result should look like this:

Spacing Control in Inspector controls

Gutenberg provides the editor.BlockEdit hook to extend the blocks edit component (which includes the InspectorControl part).

const { createHigherOrderComponent } = wp.compose;
const { Fragment } = wp.element;
const { InspectorControls } = wp.editor;
const { PanelBody, SelectControl } = wp.components;

/**
 * Create HOC to add spacing control to inspector controls of block.
 */
const withSpacingControl = createHigherOrderComponent( ( BlockEdit ) => {
    return ( props ) => {
        // Do nothing if it's another block than our defined ones.
        if ( ! enableSpacingControlOnBlocks.includes( props.name ) ) {
            return (
                <BlockEdit { ...props } />
            );
        }

        const { spacing } = props.attributes;

        return (
            <Fragment>
                <BlockEdit { ...props } />
                <InspectorControls>
                    <PanelBody
                        title={ __( 'My Spacing Control' ) }
                        initialOpen={ true }
                    >
                        <SelectControl
                            label={ __( 'Spacing' ) }
                            value={ spacing }
                            options={ spacingControlOptions }
                            onChange={ ( selectedSpacingOption ) => {
                                props.setAttributes( {
                                    spacing: selectedSpacingOption,
                                } );
                            } }
                        />
                    </PanelBody>
                </InspectorControls>
            </Fragment>
        );
    };
}, 'withSpacingControl' );

addFilter( 'editor.BlockEdit', 'extend-block-example/with-spacing-control', withSpacingControl );

We first create a Higher Order Component (HOC) withSpacingControl. It receives the original block BlockEdit component which we can extend.

if ( ! enableSpacingControlOnBlocks.includes( props.name ) ) {
    return (
        <BlockEdit { ...props } />
    );
}

We again check if the block is one of our defined blocks in the enableSpacingControlOnBlocks array. If this isn't the case we return the original BlockEdit component.

const { spacing } = props.attributes;

return (
    <Fragment>
        <BlockEdit { ...props } />
        <InspectorControls>
            <PanelBody
                title={ __( 'My Spacing Control' ) }
                initialOpen={ true }
            >
                <SelectControl
                    label={ __( 'Spacing' ) }
                    value={ spacing }
                    options={ spacingControlOptions }
                    onChange={ ( selectedSpacingOption ) => {
                        props.setAttributes( {
                            spacing: selectedSpacingOption,
                        } );
                    } }
                />
            </PanelBody>
        </InspectorControls>
    </Fragment>
);

Otherwise we wrap the original BlockEdit component in a Fragment and add a SelectControl inside the InspectorControls of the block where the spacing can be chosen.

addFilter( 'editor.BlockEdit', 'extend-block-example/with-spacing-control', withSpacingControl );

To make it work we add our withSpacingControl component to the editor.BlockEdit filter.

The spacing control should now be visible in the WordPress editor as soon as you add an image block.

3. Add margin to the saved markup

We can already select a spacing value in the backend but the change is not yet visible in the frontend. We need to use our spacing attribute to render a specific margin below the image block. We can use the blocks.getSaveContent.extraProps filter to do exactly that. With this filter we can modify the properties of the blocks save element. What we will do is map our chosen spacing to a pixel value which we add as margin-bottom to the image block.

/**
 * Add margin style attribute to save element of block.
 *
 * @param {object} saveElementProps Props of save element.
 * @param {Object} blockType Block type information.
 * @param {Object} attributes Attributes of block.
 *
 * @returns {object} Modified props of save element.
 */
const addSpacingExtraProps = ( saveElementProps, blockType, attributes ) => {
    // Do nothing if it's another block than our defined ones.
    if ( ! enableSpacingControlOnBlocks.includes( blockType.name ) ) {
        return saveElementProps;
    }

    const margins = {
        small: '5px',
        medium: '15px',
        large: '30px',
    };

    if ( attributes.spacing in margins ) {
        // Use Lodash's assign to gracefully handle if attributes are undefined
        assign( saveElementProps, { style: { 'margin-bottom': margins[ attributes.spacing ] } } );
    }

    return saveElementProps;
};

addFilter( 'blocks.getSaveContent.extraProps', 'extend-block-example/get-save-content/extra-props', addSpacingExtraProps );

In the addSpacingExtraProps function we create a little mapping object where which we can use to map our selected spacing value (small, medium or large) to an appropriate pixel value.
Afterwards we add this value as margin-bottom to the style attribute of the block.

That's already it! Our selected spacing value gets mapped to an appropriate margin-bottom value and is added to the saved markup of the block.

Wrap up

It's not that hard to extend an existing Gutenberg block. So before creating a new block think about if it would make more sense to extend an existing block to your own needs.

This tutorial is also available as a WordPress plugin on GitHub: https://github.com/liip/extend-block-example-wp-plugin. Feel free to use it as a starting point to extend Gutenberg blocks in your WordPress site.


Tell us what you think