diff --git a/docs/getting-started/tutorials/create-block/block-code.md b/docs/getting-started/tutorials/create-block/block-code.md index 441d847e58251..8a82d6c975dfd 100644 --- a/docs/getting-started/tutorials/create-block/block-code.md +++ b/docs/getting-started/tutorials/create-block/block-code.md @@ -12,7 +12,7 @@ In the `gutenpride.php` file, the enqueue process is already setup from the gene ```php function create_block_gutenpride_block_init() { - register_block_type_from_metadata( __DIR__ ); + register_block_type( __DIR__ ); } add_action( 'init', 'create_block_gutenpride_block_init' ); ``` diff --git a/docs/getting-started/tutorials/create-block/wp-plugin.md b/docs/getting-started/tutorials/create-block/wp-plugin.md index d2993aa7c65f8..b3d4a4a636e8c 100644 --- a/docs/getting-started/tutorials/create-block/wp-plugin.md +++ b/docs/getting-started/tutorials/create-block/wp-plugin.md @@ -92,12 +92,12 @@ To load the built script, so it is run within the editor, you need to tell WordP ```php function create_block_gutenpride_block_init() { - register_block_type_from_metadata( __DIR__ ); + register_block_type( __DIR__ ); } add_action( 'init', 'create_block_gutenpride_block_init' ); ``` -The `register_block_type_from_metadata` function registers the block we are going to create and specifies the `editor_script` file handle registered from the metadata provided in `block.json` file. So now when the editor loads it will load this script. +The `register_block_type` function registers the block we are going to create and specifies the editor script handle registered from the metadata provided in `block.json` file with the `editorScript` field. So now when the editor loads it will load this script. ```json { @@ -137,6 +137,6 @@ For more info, see the build section of the [Getting Started with JavaScript tut ## Summary -Hopefully, at this point, you have your plugin created and activated. We have the package.json with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor. +Hopefully, at this point, you have your plugin created and activated. We have the `package.json` with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor. Next Section: [Anatomy of a Block](/docs/getting-started/tutorials/create-block/block-anatomy.md) diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index c1a1a695650ce..aef09b567a1d4 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -1,11 +1,6 @@ # Metadata -To register a new block type using metadata that can be shared between codebase that uses JavaScript and PHP, start by creating a `block.json` file. This file: - -- Gives a name to the block type. -- Defines some important metadata about the registered block type (title, category, icon, description, keywords). -- Defines the attributes of the block type. -- Registers all the scripts and styles for your block type. +Starting in WordPress 5.8 release, we encourage using the `block.json` metadata file as the canonical way to register block types. Here is an example `block.json` file that would define the metadata for a plugin create a notice block. **Example:** @@ -50,9 +45,19 @@ To register a new block type using metadata that can be shared between codebase } ``` -The same file is also used when [submitting block to Block Directory](/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md). +## Benefits using the metadata file + +The block definition allows code sharing between JavaScript, PHP, and other languages when processing block types stored as JSON, 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 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](https://developer.wordpress.org/rest-api/reference/block-types/) 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](https://wordpress.org/plugins/) 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](/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md), all blocks contained in your plugin must have a `block.json` file for the Block Directory to recognize them. -## Server-side registration +## Block registration + +### PHP (server-side) The [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) function that aims to simplify the block type registration on the server, can read metadata stored in the `block.json` file. @@ -75,6 +80,41 @@ register_block_type( ); ``` +### JavaScript (client-side) + +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:** + +```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:** + +```js +import { registerBlockType } from '@wordpress/blocks'; +import Edit from './edit'; +import metadata from './block.json'; + +registerBlockType( metadata, { + edit: Edit, + // ...other client-side settings +} ); +``` + ## Block API This section describes all the properties that can be added to the `block.json` file to define the behavior and metadata of block types. diff --git a/docs/reference-guides/block-api/block-registration.md b/docs/reference-guides/block-api/block-registration.md index 23723ffe2f1ef..a290d4b7d4873 100644 --- a/docs/reference-guides/block-api/block-registration.md +++ b/docs/reference-guides/block-api/block-registration.md @@ -2,7 +2,7 @@ Block registration API reference. -**Note:** You can use the functions documented on this page, but a flexible method to register new block types is to use the block.json metadata file. See [metadata documentation for complete information](/docs/reference-guides/block-api/block-metadata.md). +**Note:** You can use the functions documented on this page to register a block on the client-side only, but a flexible method to register new block types is to use the `block.json` metadata file. See [metadata documentation for complete information](/docs/reference-guides/block-api/block-metadata.md). ## `registerBlockType` diff --git a/docs/reference-guides/filters/block-filters.md b/docs/reference-guides/filters/block-filters.md index e44016ed3bbd2..02a28e8f43383 100644 --- a/docs/reference-guides/filters/block-filters.md +++ b/docs/reference-guides/filters/block-filters.md @@ -2,13 +2,56 @@ To modify the behavior of existing blocks, WordPress exposes several APIs: -## Filters +## Registration -The following filters are available to extend the settings for existing blocks. +The following filters are available to extend the settings for blocks during their registration. + +### `block_type_metadata` + +Filters the raw metadata loaded from the `block.json` file when registering a block type on the server with PHP. It allows applying modifications before the metadata gets processed. + +The filter takes one param: + +- `$metadata` (`array`) – metadata loaded from `block.json` for registering a block type. + +_Example_: + +```php +`, `