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( __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( __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, 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