Block API: Apply enhancements included in WordPress 5.8 (#33252)

* Block API: Apply enhancements included in WordPress 5.8
See https://make.wordpress.org/core/2021/06/23/block-api-enhancements-in-wordpress-5-8/.

* Document two new server-side filters to use when registering a block

Author: gziolo

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' );
 ```

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)

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.

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`
 

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
+<?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__ );
+```
+
+### `block_type_metadata_settings`
+
+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:_
+
+```php
+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__ );
+```
 
 ### `blocks.registerBlockType`
 
-Used to filter the block settings. It receives the block settings and the name of the registered block as arguments. Since v6.1.0 this filter is also applied to each of a block's deprecated settings.
+Used to filter the block settings when registering the block on the client with JavaScript. It receives the block settings and the name of the registered block as arguments. This filter is also applied to each of a block's deprecated settings.
 
 _Example:_
 
@@ -34,6 +77,10 @@ wp.hooks.addFilter(
 );
 ```
 
+## Block Editor
+
+The following filters are available to change the behavior of blocks while editing in the block editor.
+
 ### `blocks.getSaveElement`
 
 A filter that applies to the result of a block's `save` function. This filter is used to replace or extend the element, for example using `wp.element.cloneElement` to modify the element's props or replace its children, or returning an entirely new element.
@@ -221,30 +268,6 @@ wp.hooks.addFilter(
 
 {% end %}
 
-#### `media.crossOrigin`
-
-Used to set or modify the `crossOrigin` attribute for foreign-origin media elements (i.e `<img>`, `<audio>` , `<img>` , `<link>` , `<script>`, `<video>`). See this [article](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) for more information the `crossOrigin` attribute, its values and how it applies to each element.
-
-One example of it in action is in the Image block's transform feature to allow cross-origin images to be used in a `<canvas>`.
-
-_Example:_
-
-```js
-addFilter(
-	'media.crossOrigin',
-	'my-plugin/with-cors-media',
-	// The callback accepts a second `mediaSrc` argument which references
-	// the url to actual foreign media, useful if you want to decide
-	// the value of crossOrigin based upon it.
-	( crossOrigin, mediaSrc ) => {
-		if ( mediaSrc.startsWith( 'https://example.com' ) ) {
-			return 'use-credentials';
-		}
-		return crossOrigin;
-	}
-);
-```
-
 ## Removing Blocks
 
 ### Using a deny list

docs/reference-guides/filters/editor-filters.md

@@ -38,6 +38,30 @@ wp.hooks.addFilter(
 );
 ```
 
+### `media.crossOrigin`
+
+Used to set or modify the `crossOrigin` attribute for foreign-origin media elements (i.e `<img>`, `<audio>` , `<img>` , `<link>` , `<script>`, `<video>`). See this [article](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) for more information the `crossOrigin` attribute, its values and how it applies to each element.
+
+One example of it in action is in the Image block's transform feature to allow cross-origin images to be used in a `<canvas>`.
+
+_Example:_
+
+```js
+addFilter(
+	'media.crossOrigin',
+	'my-plugin/with-cors-media',
+	// The callback accepts a second `mediaSrc` argument which references
+	// the url to actual foreign media, useful if you want to decide
+	// the value of crossOrigin based upon it.
+	( crossOrigin, mediaSrc ) => {
+		if ( mediaSrc.startsWith( 'https://example.com' ) ) {
+			return 'use-credentials';
+		}
+		return crossOrigin;
+	}
+);
+```
+
 ## Editor settings
 
 ### `block_editor_settings`

packages/create-block-tutorial-template/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Enhancement
+
+-   Plugin scaffolded requires WordPress 5.8 now ([#33252](https://github.com/WordPress/gutenberg/pull/33252).
+-   Scaffolded block is now registered from `block.json` with the `register_block_type` helper ([#33252](https://github.com/WordPress/gutenberg/pull/33252)).
+
 ## 1.2.0 (2021-04-06)
 
 ### Enhancement

packages/create-block-tutorial-template/templates/$slug.php.mustache

@@ -4,7 +4,7 @@
 {{#description}}
  * Description:       {{description}}
 {{/description}}
- * Requires at least: 5.7
+ * Requires at least: 5.8
  * Requires PHP:      7.0
  * Version:           {{version}}
 {{#author}}
@@ -29,6 +29,6 @@
  * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
  */
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
-	register_block_type_from_metadata( __DIR__ );
+	register_block_type( __DIR__ );
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );

packages/create-block/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Enhancement
+
+-   Plugin scaffolded with the `esnext` template requires WordPress 5.8 now ([#33252](https://github.com/WordPress/gutenberg/pull/33252).
+-   Block scaffolded with the `esnext` template is now registered from `block.json` with the `register_block_type` helper ([#33252](https://github.com/WordPress/gutenberg/pull/33252)).
+
 ## 2.3.0 (2021-04-29)
 
 ### Enhancement

packages/create-block/lib/templates/esnext/$slug.php.mustache

@@ -4,7 +4,7 @@
 {{#description}}
  * Description:       {{description}}
 {{/description}}
- * Requires at least: 5.7
+ * Requires at least: 5.8
  * Requires PHP:      7.0
  * Version:           {{version}}
 {{#author}}
@@ -29,6 +29,6 @@
  * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
  */
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
-	register_block_type_from_metadata( __DIR__ );
+	register_block_type( __DIR__ );
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );