Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add section in block RFC about register_block_type_from_metadata #21501

Merged
merged 1 commit into from
Apr 10, 2020
Merged

Docs: Add section in block RFC about register_block_type_from_metadata #21501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 47 additions & 21 deletions docs/rfc/block-registration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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" }
]
}
Expand Down Expand Up @@ -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', {
Expand All @@ -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.

Expand All @@ -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
<?php
return array(
'dependencies' => array(
'wp-blocks',
'wp-element',
'wp-i18n',
),
'version' => '3be55b05081a63d8f9d0ecb466c42cfd',
);
```

## Internationalization
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion lib/compat.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down