From 2a5146f6a078ae4ebfb9b0b806daac17674e7a95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=28Greg=29=20Zi=C3=B3=C5=82kowski?= Date: Fri, 10 Apr 2020 06:24:13 +0200 Subject: [PATCH] Docs: Add section in block RFC about register_block_type_from_metadata (#21501) --- docs/rfc/block-registration.md | 68 +++++++++++++++++++++++----------- lib/compat.php | 2 +- 2 files changed, 48 insertions(+), 22 deletions(-) diff --git a/docs/rfc/block-registration.md b/docs/rfc/block-registration.md index c1844e1646a42f..9ae9d5ad4b1de5 100644 --- a/docs/rfc/block-registration.md +++ b/docs/rfc/block-registration.md @@ -32,7 +32,7 @@ Initial support for server-defined block attributes was merged as part of [#2529 A demonstration for how block registration could be made filterable in PHP was explored in [#5802](https://github.com/WordPress/gutenberg/pull/5802). The purpose here was to explore how plugins could have better control over the registration. -Another exploration in [#5652](https://github.com/WordPress/gutenberg/pull/5652) considered using JSON as a file format to share block type definitions between JavaScript and PHP. +Another exploration in [#5652](https://github.com/WordPress/gutenberg/pull/5652) considered using JSON as a file format to share block type definitions between JavaScript and PHP. ### Conclusions @@ -77,8 +77,8 @@ To register a new block type, start by creating a `block.json` file. This file: "selector": ".message" } }, - "styleVariations": [ - { "name": "default", "label": "Default", "isDefault": true }, + "styleVariations": [ + { "name": "default", "label": "Default", "isDefault": true }, { "name": "other", "label": "Other" } ], "editorScript": "build/editor.js", @@ -222,7 +222,7 @@ The [gettext](https://www.gnu.org/software/gettext/) text domain of the plugin/b * Property: `attributes` ```json -{ +{ "attributes": { "cover": { "type": "string", @@ -252,9 +252,9 @@ See the [the attributes documentation](/docs/designers-developers/developers/blo * Alias: `styleVariations` ```json -{ - "styleVariations": [ - { "name": "default", "label": "Default", "isDefault": true }, +{ + "styleVariations": [ + { "name": "default", "label": "Default", "isDefault": true }, { "name": "other", "label": "Other" } ] } @@ -326,7 +326,7 @@ The following properties are going to be supported for backward compatibility re - `supports` - see the [block supports](/docs/designers-developers/developers/block-api/block-registration.md#supports-optional) documentation page for more details. - `merge` - undocumented as of today. Its role is to handle merging multiple blocks into one. - `getEditWrapperProps` - undocumented as well. Its role is to inject additional props to the block edit's component wrapper. - + **Example**: ```js wp.blocks.registerBlockType( 'my-block/name', { @@ -340,7 +340,7 @@ wp.blocks.registerBlockType( 'my-block/name', { html: false } } ); -``` +``` In the case of [dynamic blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md) supported by WordPress, it should be still possible to register `render_callback` property using [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) function on the server. @@ -365,31 +365,35 @@ That's why, the `WPDefinedAsset` type has to offer a way to mirror also the shap It's possible to provide an object which takes the following shape: - `handle` (`string`) - the name of the script. If omitted, it will be auto-generated. -- `dependencies` (`string[]`) - an array of registered script handles this script depends on. Default value: `[]`. +- `dependencies` (`string[]`) - an array of registered script handles this script depends on. Default value: `[]`. - `version` (`string`|`false`|`null`) - string specifying the script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If the version is set to `false`, a version number is automatically added equal to current installed WordPress version. If set to `null`, no version is added. Default value: `false`. -The definition is stored inside separate JSON file which ends with `.asset.json` and is located next to the JS/CSS file listed in `block.json`. WordPress will automatically detect this file through pattern matching. This option is the preferred one as it is expected it will become an option to auto-generate those asset files with `@wordpress/scripts` package. +The definition is stored inside separate PHP file which ends with `.asset.php` and is located next to the JS/CSS file listed in `block.json`. WordPress will automatically detect this file through pattern matching. This option is the preferred one as it is expected it will become an option to auto-generate those asset files with `@wordpress/scripts` package. **Example:** ``` build/ -├─ editor.js -└─ editor.asset.json +├─ index.js +└─ index.asset.php ``` In `block.json`: ```json -{ "editorScript": "build/editor.js" } +{ "editorScript": "build/index.js" } ``` -In `build/editor.asset.json`: -```json -{ - "handle": "my-plugin-notice-editor", - "dependencies": [ "wp-blocks","wp-element", "wp-i18n" ], - "version": "3.0.0" -} +In `build/index.asset.php`: +```php + array( + 'wp-blocks', + 'wp-element', + 'wp-i18n', + ), + 'version' => '3be55b05081a63d8f9d0ecb466c42cfd', +); ``` ## Internationalization @@ -432,6 +436,28 @@ $metadata = array( Implementation should follow 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. +## Server-side registration + +There is also a new API method proposed `register_block_type_from_metadata` that aims to simplify the block type registration on the server from metadata stored in the `block.json` file. This function is going to handle also all necessary work to make internationalization work seamlessly for metadata defined. + +This function takes two params: +- `$path` (`string`) – path to the folder where the `block.json` file is located. +- `$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__ . '/shortcode', + array( + 'render_callback' => 'render_block_core_shortcode', + ) +); +``` + ## Backward Compatibility The existing registration mechanism (both server side and frontend) will continue to work, it will serve as low-level implementation detail for the `block.json` based registration. diff --git a/lib/compat.php b/lib/compat.php index 80c3e460bf8bb2..f05a9b102feb34 100644 --- a/lib/compat.php +++ b/lib/compat.php @@ -12,7 +12,7 @@ /** * Registers a block type from metadata stored in the `block.json` file. * - * @since 7.8.0 + * @since 7.9.0 * * @param string $path Path to the folder where the `block.json` file is located. * @param array $args {