README.md

Gutenberg Fields Middleware

---

IMPORTANT

The work on Gutenberg Fields Middleware had started during the initial development phase of Gutenberg before it was merged into core. Gutenberg has evolved a lot since then and with the introduction of InnerBlocks and block templates, Gutenberg Fields Middleware has become less useful because the core blocks can be used as fields for creating blocks using block templates. Therefore we have stopped the development of this project and would archive this repo.

---

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

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.

1. As a 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-blocks', 'wp-i18n', 'wp-element', 'wp-date', 'wp-hooks' ) 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',
) );

✔️ Gutenberg fields middleware is also available as npm package.

npm i gutenberg-fields-middleware

Available Fields

Gutenberg Fields Middleware supports the following field types and type configuration.

• alignment-toolbar
• audio
• block-alignment-toolbar
• button-editable
• checkbox
• code-editor
• color
• date-time
• dropdown-menu
• file-upload
• icons-toolbar
• image
• input types: email / number/ hidden / search / tel etc.
• link
• media-icon
• radio
• range
• rich-text
• select
• switch
• text
• textarea
• tree-select
• url-input-button
• video

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.

Does this interest you?