Gutenberg Fields Middleware

Register fields for Gutenberg blocks with a simple, declarative API.

This project is in its early stages. Please open an issue with questions, feedback, suggestions, and bug reports.

Using | Available Fields

Installation

$ npm i gutenberg-fields-middleware

To include Middleware in your JS file add import statement at the top of the file

import 'gutenberg-fields-middleware';

Using

Gutenberg fields middleware requires only two files dist/middleware.min.js and dist/middleware.min.css as dependency.

There are two ways of using fields middleware.

There are two ways of using the middleware.

1. As a WordPress Plugin: Install the Gutenberg Fields Middleware as a standalone WordPress plugin which will register a gutenberg-fields-middleware handle you can add as a dependency for your block script.
2. Using JS and CSS files: Or you can use middleware.min.js and middleware.min.css and enqueue them as dependency for your block script. Be sure to use array( 'wp-editor', 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-date', 'underscore' ) handles as your dependency when enqueing middleware js file.

Fields are now registered as attribute configuration details. Here's how you might register image, text, color and range fields:

wp.blocks.registerBlockType( 'example-namespace/example-block', {
    title: 'Example Block',
    category: 'common',
    attributes: {
        image: {
            type: 'object',
            field: {
                type: 'image',
            },
        },
        text: {
            type: 'string',
            field: {
                type: 'text',
                placeholder: 'Enter text..',
            },
        },
        color: {
            type: 'string',
            field: {
                type: 'color',
                placement: 'inspector',
            },
        },
        range: {
            type: 'string',
            field: {
                type: 'range',
                label: 'Columns',
                placement: 'inspector', // To show in sidebar.
            },
            default: 20,
        },
    },
 
    edit: function( props, middleware ) {
        return [
            middleware.inspectorControls, // Contains ALL inspector controls.
            middleware.fields.image,
            middleware.fields.text,
        ];
    },
 
    save: function( props ) {}
});

Which will create a block like this

✔️ Fields can also be used in the same way when using register_block_type in PHP.

register_block_type( 'example-namespace/example-block', array(
    'attributes' => array(
        'image' => array(
            'type' => 'object',
            'field' => array(
                'type' => 'image',
                'buttonText' => 'Upload',
                'imagePlaceholder' => true,
                'removeButtonText' => 'Remove',
            ),
        ),
        'color' => array(
            'type' => 'string',
            'field' => array(
                'type' => 'color'
            )
        )
    ),
    'render_callback' => 'example_callback',
) );

Returning field in edit method:

• middleware.fields.arrtibuteKeyName for a single field when placement property is not defined.
• middleware.blockControls for all block-control fields. ( where placement is block-control )
• middleware.inspectorControls for all inspector fields. ( where placement is inspector )

Getting more control over fields:

There are two ways of getting a field, one is simply use middleware.fields.arrtibuteKeyName or middleware.getField( props, 'arrtibuteKeyName', config ) when you need more control over a field, here you can use all configuration options in config parameter given in the fields doc.

The same can be done for block controls and inspector controls as middleware.getBlockControls( props, fields ) and middleware.getInspectorControls( props, fields ) where fields can be defined as an array of fields.

See example usage of alignment-toolbar.

Example Usage:

• See examples
  • You can set GUTENBERG_FIELDS_MIDDLEWARE_IS_DEV to true during development in wp-config.php which will also enable example blocks.
• Check gutenberg-supplements plugin where we have created some actual blocks using middleware.

Documentation

Read docs on github