Greg Ziółkowski 5:31 pm on June 23, 2021
Tags: 5.8 ( 99 ), dev-notes ( 520 ), gutenberg ( 476 )

Block API Enhancements in WordPress 5.8

Starting in WordPress 5.8 release, we encourage using the block.json metadata file as the canonical way to register blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. types. The Block Metadata specification has been implemented and iterated over the last few major WordPress releases, and we have reached the point where all planned features are in place.

Example File

Here is an example block.json file that would define the metadata for a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party create a notice block.

notice/block.json

{
	"apiVersion": 2,
	"name": "my-plugin/notice",
	"title": "Notice",
	"category": "text",
	"parent": [ "core/group" ],
	"icon": "star",
	"description": "Shows warning, error or success notices…",
	"keywords": [ "alert", "message" ],
	"textdomain": "my-plugin",
	"attributes": {
		"message": {
			"type": "string",
			"source": "html",
			"selector": ".message"
		}
	},
	"providesContext": {
		"my-plugin/message": "message"
	},
	"usesContext": [ "groupId" ],
	"supports": {
		"align": true
	},
	"styles": [
		{ "name": "default", "label": "Default", "isDefault": true },
		{ "name": "other", "label": "Other" }
	],
	"example": {
		"attributes": {
			"message": "This is a notice!"
		}
	},
	"editorScript": "file:./build/index.js",
	"script": "file:./build/script.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style.css"
}

Benefits using the metadata file

The block definition allows code sharing between JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/., PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher, and other languages when processing block types stored as JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., and registering blocks with the block.json metadata file provides multiple benefits on top of it.

From a performance perspective, when themes support lazy loading assets, blocks registered with block.json will have their asset enqueuing optimized out of the box. The frontend CSSCSS Cascading Style Sheets. and JavaScript assets listed in the style or script properties will only be enqueued when the block is present on the page, resulting in reduced page sizes.

Furthermore, because the Block Type REST API Endpoint can only list blocks registered on the server, registering blocks server-side is recommended; using the block.json file simplifies this registration.

Last, but not least, the WordPress Plugins Directory can detect block.json files, highlight blocks included in plugins, and extract their metadata. If you wish to submit your block(s) to the Block Directory, all blocks contained in your plugin must have a block.json file for the Block Directory to recognize them.

Block registration

PHP

The register_block_type function that aims to simplify the block type registration on the server, can read now metadata stored in the block.json file.

The function takes two params relevant in this context ($block_type accepts more types and variants):

$block_type (string) – path to the folder where the block.json file is located or full path to the metadata file if named differently.
$args (array) – an optional array of block type arguments. Default value: []. Any arguments may be defined.

It returns the registered block type (WP_Block_Type) on success or false on failure.

Example:

notice/notice.php

<?php

register_block_type(
	__DIR__,
	array(
		'render_callback' => 'render_block_core_notice',
	)
);

Note: We decided to consolidate the pre-existing functionality available with register_block_type_from_metadata method into register_block_type to avoid some confusion that it created. It’s still possible to use both functions, but we plan to use only the shorter version in the official documents and tools from now on.

Related TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker.: #53233.

JavaScript

When the block is registered on the server, you only need to register the client-side settings on the client using the same block’s name.

Example:

notice/index.js

registerBlockType( 'my-plugin/notice', {
	edit: Edit,
	// ...other client-side settings
} );

Although registering the block also on the server with PHP is still recommended for the reasons above, if you want to register it only client-side you can now use registerBlockType method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file.

The function takes two params:

$blockNameOrMetadata (string|Object) – block type name (supported previously) or the metadata object loaded from the block.json file with a bundler (e.g., webpack) or a custom Babel plugin.
$settings (Object) – client-side block settings.

It returns the registered block type (WPBlock) on success or undefined on failure.

Example:

notice/index.js

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
	edit: Edit,
	// ...other client-side settings
} );

Related PR: WordPress/gutenberg#32030.

Internationalization support in `block.json`

WordPress string discovery system can now automatically translate fields marked as translatable in Block Metadata document. First, in the block.json file that provides block metadata, you need to set the textdomain property and fields that should be translated.

Example:

fantastic-block/block.json

{
	"name": "my-plugin/fantastic-block",
	"title": "My block",
	"description": "My block is fantastic",
	"keywords": [ "fantastic" ],
	"textdomain": "fantastic-block"
}

PHP

In PHP, localized properties will be automatically wrapped in _x function calls on the backend of WordPress when executing register_block_type function. These translations get added as an inline script to the plugin’s script handle or to the wp-block-library script handle in WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

The way register_block_type processes translatable values is roughly equivalent to the following code snippet:

<?php
$metadata = array(
	'title'       => _x( 'My block', 'block title', 'fantastic-block' ),
	'description' => _x( 'My block is fantastic!', 'block description', 'fantastic-block' ),
	'keywords'    => array( _x( 'fantastic', 'block keyword', 'fantastic-block' ) ),
);

Implementation follows the existing get_plugin_data function which parses the plugin contents to retrieve the plugin’s metadata, and it applies translations dynamically.

Related Trac ticket: #52301.

JavaScript

You can also now use registerBlockType method from @wordpress/blocks package to register a block type that uses translatable metadata stored in block.json file. All localized properties get automatically wrapped in _x function calls (from @wordpress/i18n package) similar to how it works in PHP with register_block_type. The only requirement is to set the textdomain property in the block.json file.

Example:

fantastic-block/index.js

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
	edit: Edit,
	// ...other client-side settings
} );

Related PR: WordPress/gutenberg#30293.

Extracting translations

The ongoing effort to improve the internationalization of client-side JavaScript code made necessary by moving to the block-based editor has led to several improvements to the i18n make-pot command from WP-CLI as of v2.5.0 release. It now also parses the block.json file as it is defined in the Block Metadata document.

Related PR: wp-cli/i18n-command#210.

New filters

There are two new WordPress hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. that can be used when block types get registered with register_block_type function using the metadata loaded from the block.json file.

`block_type_metadata`

Filters the raw metadata loaded from the block.json file when registering a block type. It allows applying modifications before the metadata gets processed.

The filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. takes one param:

$metadata (array) – metadata loaded from block.json for registering a block type.

Example:

<?php

function filter_metadata_registration( $metadata ) {
	$metadata['apiVersion'] = 1;
	return $metadata;
};
add_filter( 'block_type_metadata', 'filter_metadata_registration', 10, 2 );

register_block_type( __DIR__ );

`block_type_metadata_settings`

Filters the settings determined from the processed block type metadata. It makes it possible to apply custom modifications using the block metadata that isn’t handled by default.

The filter takes two params:

$settings (array) – Array of determined settings for registering a block type.
$metadata (array) – Metadata loaded from the block.json file.

Example:

function filter_metadata_registration( $settings, $metadata ) {
	$settings['api_version'] = $metadata['apiVersion'] + 1;
	return $settings;
};
add_filter( 'block_type_metadata_settings', 'filter_metadata_registration', 10, 2 );
		
register_block_type( __DIR__ );

Props to @priethor and @audrasjb for help with compiling this dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase..

#5-8, #dev-notes, #gutenberg

andrejcremoznik 7:57 am on June 24, 2021

so in short,

1. do `register_block_type` in PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher giving it the dir with the `block.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.`
2. `block.json` enqueues the `editorScript`
3. the `editorScript` should not call `registerBlockType`

This post tells me nothing about the `editorScript`. The way it works in https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/index.js blocks are registered with `registerBlockType` which is, according to this post, discouraged in favor of PHP’s `register_block_type`.

What are the requirements for the `editorScript`? I suppose it needs to export a global object. What is the name of the global variable? What are the requirements for the exported object? I assume the same as what `registerBlockType` expects?
- Greg Ziółkowski 12:33 pm on June 24, 2021
  
  > the `editorScript` should not call `registerBlockType`
  
  This is incorrect. You still need to call `registerBlockType` function on the client using the same blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. name and provide at least `edit` implementation for the block to register it on the client. In general, everything that can’t be serialized in JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. format like JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. functions needs to be handled on the client.
  
  We are going to update the post and clarify it better. The short answer is that the `editorScript` script needs to contain the `registerBlockType` call.
  - andrejcremoznik 7:19 am on June 28, 2021
    
    Thanks for clarifying. The way this post is/was written it seems as if the server and client-side registration are exclusive, which wouldn’t be surprising given quite a few discrepancies between the current 5.8 branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". and available documentation.
Sandesh 10:42 am on June 30, 2021
```
The frontend CSS and JavaScript assets listed in the style or script properties will only be enqueued when the block is present on the page, resulting in reduced page sizes.
```
How can we enqueue dependent js script? As mentioned in the example, I can only enqueue 1js script per blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience..
- Greg Ziółkowski 10:28 am on July 5, 2021
  Yes, it is a know limitation that hasn’t been raised as an issue so far in the context of scripts. It is something that @aristath considers for styles though. Initial exploration can be found in https://github.com/WordPress/gutenberg/pull/32510 (it won’t be included in WordPress 5.8). We need to agree on the path forward and apply all the necessary changes to blocks and their styles and scripts.
  
  For the time being, it’s possible to define a script handle name as `script` or `editorScript` and register a script that doesn’t have a URI but acts as an alias to dependent scripts, some pseudo-code that might help:
```
wp_register_script(
    'script-handle',
    false,
    array( 'script-handle-1', 'script-handle-2' )
); 
```
wpexplorer 10:30 pm on July 13, 2021

I understand you still need to use the registerBlockType function on the client and provide at least the “edit” implementation, however, it would be ideal to streamline things and have InspectorControls automatically generated from the attributes defined block.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. – why not just loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. through the attributes and automatically generate Inspector Controls for any attribute that doesn’t have a defined “source”?
- Greg Ziółkowski 7:28 am on July 14, 2021
  
  There are 3 places where you can edit attributes, and it isn’t only `InspectorControls`. It’s also the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. canvas and `BlockToolbars`. Each of them has different implementation requirements.
  
  I understand you would like to handle those attributes that are somehow channeled there automatically. In practice, you need to provide more details to render UIUI User interface for those controls – at least the label for the form field. I’m sure the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. would grow pretty quick as there would be other requirements like value ranges or pattern matching – basically everything comes to my mind that HTML5 offers with forms.
  
  It’s also worth noting that to some degree the ongoing efforts to build Global Styles UI should address the concern you shared. There is a growing number of options in Block supports API that aim to automate the handling of block attributes. When you use this API you even don’t have to explicitly define the attribute, it’s handled behind the scenes when necessary.
  
  Anyway, I agree that the issue exists and we should look at it much closer again once the Global Styles UI is fully functional.
Fernando Tessmann 12:19 pm on July 14, 2021

Hi @gziolo, thanks for the blogblog (versus network, site) post and updates. I’ve already started to use this new way to build Blocks and it has a great developer experience.

Question about the 4 entries on block.json related to the scripts and styles: the WP functions register_block_script_handle and register_block_style_handle are explicitly using plugins_url to declare/get the asset URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. Which implies it’s impossible (without a workaround) to create blocks within the theme.

We know it’s the recommendation to use plugins to create blocks, but usually, in the WordPress world, “pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party territory” implementations within a theme are best practices and don’t break.

Is this the expected behaviour? To make this work on a theme, I needed to use the filters script_loader_src and style_loader_src to fix the URL of each asset related to the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience..

Thank you!
- Greg Ziółkowski 8:49 am on July 15, 2021
  
  > Which implies it’s impossible (without a workaround) to create blocks within the theme.
  
  I would phrase it as we discourage storing blocks in the theme. The reason is that as soon as the user switches the theme, they will lose the UIUI User interface for editing such blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.. As you noted it’s possible to work around it with filters or you could register assets yourself and pass the handles for those assets in block.json. In both cases, the block would still benefit from the optimizations applied behind the scenes.
  
  If there is a strong desire to make the asset URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org work with both themes and plugins then we can always reconsider it. It’s a simple code change, so it’s mostly about changing the prior decision.
Sergio de Falco 4:36 pm on July 14, 2021

Great, just one question, for ones of us that are updating old BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. plugins can we full switch to the block.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. or do we have to leave the old method working in order to be compatible with older WordPress versions?

Thanks!
- Greg Ziółkowski 9:36 am on July 15, 2021
  
  What is the current implementation that you have? I would say it all depends on which versions of WordPress are you willing to support and how your setup looks like.
  
  There is register_block_type_from_metadata function introduced in WP 5.5 that can be used as a fallback for WP 5.5-5.7 to register blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. with block.json but some features were added only in WP 5.7 like automatically applied translations for fields stored in block.json. In general, register_block_type_from_metadata can be used as a transitional way of registering blocks on the server until WP 5.8 becomes the minimum supported version for your blocks.
  
  It’s also worth emphasizing that it always will be possible to register a block only on the client with wp.blocks.registerBlockType. I consider block registration on the server as a progressive enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. that allows WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. to optimize the experience for all users in terms of performance, extensibility, discoverability, etc.
  - Sergio de Falco 11:00 am on July 15, 2021
    
    Thanks for your reply @gziolo My pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party is implementing the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. enqueuing the javascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. file via wp_enqueue_script inside a enqueue_block_editor_assets action.
    It’s an old plugin that now needs some upgrades.
    
    So following your suggestions I think I will increase the minimum WP version to 5.5 and I will use register_block_type_from_metadata as fallback.
    
    Thanks!
wpsoul 10:01 pm on July 19, 2021

block.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. is great when you have only one asset file for blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.. it’s totally useless for complex blocks which has conditional and third party libraries. Why do not make it to support several files as array?

And what we can do if we have some conditional scripts? For example, I have gallery block, in this gallery block I have option to make it as slider, so, in enqueue_block_assets hook I check for attribute of block and load slider library if it’s enabled. Block.json is very very limited for such scenarios. To be truth, it’s not usable at all
- Greg Ziółkowski 7:20 am on July 20, 2021
  
  Good point about supporting multiple asset files of a given type for the individual blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.. I filed an issue https://github.com/WordPress/gutenberg/issues/33542 that covers this popular feedback. There is even a PR https://github.com/WordPress/gutenberg/pull/32510 ready for styles from @aristath that is close to ready to be integrated with the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party.
  
  Conditional loading of scripts for the block is a valid use case that was also coded recently in the Gutenberg plugin. The File block and Navigation block use this technique. We are introducing a new asset type viewScript that registers the script, but the plugin author can conditionally load it using render_callback, example:
  https://github.com/WordPress/gutenberg/blob/5aa3559ef737121a82e36dedec4514aa83895e16/packages/block-library/src/file/index.php#L16-L23
mtedwards 1:07 am on August 27, 2021

Is there a link to an example of best practice use of this? I’m trying to create a new blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. from scratch using block.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., but I don’t seem to have access to the attributes in my edit.js file. (It is possible I am doing something quite wrong).

Comments are closed.

Welcome!

Communication

Block API Enhancements in WordPress 5.8

Example File

Benefits using the metadata file

Block registration

PHP

JavaScript

Internationalization support in `block.json`

PHP

JavaScript

Extracting translations

New filters

`block_type_metadata`

`block_type_metadata_settings`

Welcome!

Communication

Example File

Benefits using the metadata file

Block registration

PHP

JavaScript

Internationalization support in block.json

PHP

JavaScript

Extracting translations

New filters

block_type_metadata

block_type_metadata_settings

Share this:

Internationalization support in `block.json`

`block_type_metadata`

`block_type_metadata_settings`