diff --git a/docs/designers-developers/developers/block-api/README.md b/docs/designers-developers/developers/block-api/README.md index dd8c646888293..790e694aa65ba 100644 --- a/docs/designers-developers/developers/block-api/README.md +++ b/docs/designers-developers/developers/block-api/README.md @@ -4,12 +4,15 @@ Blocks are the fundamental element of the editor. They are the primary way in wh The following sections will walk you through the existing block APIs: -- [Block registration](/docs/designers-developers/developers/block-api/block-registration.md) -- [Edit and Save](/docs/designers-developers/developers/block-api/block-edit-save.md) -- [Attributes](/docs/designers-developers/developers/block-api/block-attributes.md) -- [Deprecated blocks](/docs/designers-developers/developers/block-api/block-deprecation.md) -- [Supports](/docs/designers-developers/developers/block-api/block-supports.md) -- [Transformations](/docs/designers-developers/developers/block-api/block-transforms.md) -- [Templates](/docs/designers-developers/developers/block-api/block-templates.md) -- [Annotations](/docs/designers-developers/developers/block-api/block-annotations.md) -- [Block Patterns](/docs/designers-developers/developers/block-api/block-patterns.md) +- [Block registration](/docs/designers-developers/developers/block-api/block-registration.md) +- [Edit and Save](/docs/designers-developers/developers/block-api/block-edit-save.md) +- [Attributes](/docs/designers-developers/developers/block-api/block-attributes.md) +- [Context](/docs/designers-developers/developers/block-api/block-context.md) +- [Deprecation](/docs/designers-developers/developers/block-api/block-deprecation.md) +- [Supports](/docs/designers-developers/developers/block-api/block-supports.md) +- [Transformations](/docs/designers-developers/developers/block-api/block-transforms.md) +- [Templates](/docs/designers-developers/developers/block-api/block-templates.md) +- [Metadata](/docs/designers-developers/developers/block-api/block-metadata.md) +- [Block Patterns](/docs/designers-developers/developers/block-api/block-patterns.md) +- [Annotations](/docs/designers-developers/developers/block-api/block-annotations.md) +- [Versions](/docs/designers-developers/developers/block-api/versions.md) diff --git a/docs/designers-developers/developers/block-api/block-metadata.md b/docs/designers-developers/developers/block-api/block-metadata.md index 24d1468121ba2..4d103752b2213 100644 --- a/docs/designers-developers/developers/block-api/block-metadata.md +++ b/docs/designers-developers/developers/block-api/block-metadata.md @@ -32,7 +32,7 @@ To register a new block type using metadata that can be shared between codebase }, "usesContext": [ "groupId" ], "supports": { - "align": true, + "align": true }, "styles": [ { "name": "default", "label": "Default", "isDefault": true }, @@ -50,6 +50,29 @@ To register a new block type using metadata that can be shared between codebase } ``` +## Server-side registration + +There is also [`register_block_type_from_metadata`](https://developer.wordpress.org/reference/functions/register_block_type_from_metadata/) function that aims to simplify the block type registration on the server from metadata stored in the `block.json` file. + +This function takes two params: + +- `$path` (`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. However, the one described below is supported by default: + - `$render_callback` (`callable`) – callback used to render blocks of this block type. + +It returns the registered block type (`WP_Block_Type`) on success or `false` on failure. + +**Example:** + +```php +register_block_type_from_metadata( + __DIR__ . '/notice', + array( + 'render_callback' => 'render_block_core_notice', + ) +); +``` + ## 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. @@ -370,8 +393,6 @@ In `block.json`: } ``` -#### WordPress context - In the context of WordPress, when a block is registered with PHP, it will automatically register all scripts and styles that are found in the `block.json` file and use file paths rather than asset handles. That's why, the `WPDefinedAsset` type has to offer a way to mirror also the shape of params necessary to register scripts and styles using [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) and [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/), and then assign these as handles associated with your block using the `script`, `style`, `editor_script`, and `editor_style` block type registration settings. @@ -412,11 +433,9 @@ return array( ); ``` -## Internationalization (not implemented) +## Internationalization -Localized properties will be automatically wrapped in `_x` function calls on the backend and the frontend of WordPress. These translations are added as an inline script to the `wp-block-library` script handle in WordPress core or to the plugin's script handle when it defines metadata definition. - -WordPress string discovery automatically will translate these strings using the `textdomain` property specified in the `block.json` file. +WordPress string discovery automatically will translate fields marked in the documentation as translatable using the `textdomain` property when specified in the `block.json` file. In that case, localized properties will be automatically wrapped in `_x` function calls on the backend of WordPress when executing `register_block_type_from_metadata`. These translations are added as an inline script to the `wp-block-library` script handle in WordPress core or to the plugin's script handle. **Example:** @@ -429,21 +448,7 @@ WordPress string discovery automatically will translate these strings using the } ``` -In JavaScript, with the help of a new helper function `registerBlockTypeFromMetadata`, this becomes: - -```js -const metadata = { - title: _x( 'My block', 'block title', 'my-plugin' ), - description: _x( - 'My block is fantastic', - 'block description', - 'my-plugin' - ), - keywords: [ _x( 'fantastic', 'block keywords', 'my-plugin' ) ], -}; -``` - -In PHP, it is transformed at runtime with a new helper function `register_block_from_metadata` to code roughly equivalent to: +The way `register_block_type_from_metadata` processes translatable values is roughly equivalent to: ```php 'render_block_core_shortcode', - ) -); -``` +Implementation follows the existing [get_plugin_data](https://codex.wordpress.org/Function_Reference/get_plugin_data) function which parses the plugin contents to retrieve the plugin’s metadata, and it applies translations dynamically. ## Backward Compatibility diff --git a/docs/manifest.json b/docs/manifest.json index 24243f9766e52..cc3e74363bf0a 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -143,6 +143,12 @@ "markdown_source": "../docs/designers-developers/developers/block-api/block-templates.md", "parent": "block-api" }, + { + "title": "Block Type Metadata", + "slug": "block-metadata", + "markdown_source": "../docs/designers-developers/developers/block-api/block-metadata.md", + "parent": "block-api" + }, { "title": "Block Patterns", "slug": "block-patterns", diff --git a/docs/toc.json b/docs/toc.json index 3d685561927b4..dcf3a4699d5b2 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -25,6 +25,7 @@ { "docs/designers-developers/developers/block-api/block-supports.md": [] }, { "docs/designers-developers/developers/block-api/block-transforms.md": [] }, { "docs/designers-developers/developers/block-api/block-templates.md": [] }, + { "docs/designers-developers/developers/block-api/block-metadata.md": [] }, { "docs/designers-developers/developers/block-api/block-patterns.md": [] }, { "docs/designers-developers/developers/block-api/block-annotations.md": [] }, { "docs/designers-developers/developers/block-api/versions.md": [] }