Starting in WordPress 5.8 release, we encourage using the block.json metadata file as the canonical way to register block 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 plugin 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 JavaScript 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/., PHP 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 JSON 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 CSS 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 Trac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket 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 core 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 hooks 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.
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 filter 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_from_metadata( __DIR__ );
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_from_metadata( __DIR__ );
Props to @priethor and @audrasjb for help with compiling this dev 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
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
