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