Block Editor API: Changes to support multiple admin screens in WP 5.8 (…

…#33262)

* Block Editor API: Changes to support multiple admin screens in WP 5.8
See https://make.wordpress.org/core/2021/06/16/block-editor-api-changes-to-support-multiple-admin-screens-in-wp-5-8/.

* Add a note explaining how to use the deprecated filters

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

@@ -339,48 +339,57 @@ wp.blocks.getBlockTypes().forEach( function ( blockType ) {
 
 ## Hiding blocks from the inserter
 
-On the server, you can filter the list of blocks shown in the inserter using the `allowed_block_types` filter. You can return either true (all block types supported), false (no block types supported), or an array of block type names to allow. You can also use the second provided param `$post` to filter block types based on its content.
+### `allowed_block_types_all`
+
+_**Note:** Before WordPress 5.8 known as `allowed_block_types`. In the case when you want to support older versions of WordPress you might need a way to detect which filter should be used – the deprecated one vs the new one. The recommended way to proceed is to check if the `WP_Block_Editor_Context` class exists._
+
+On the server, you can filter the list of blocks shown in the inserter using the `allowed_block_types_all` filter. You can return either true (all block types supported), false (no block types supported), or an array of block type names to allow. You can also use the second provided param `$editor_context` to filter block types based on its content.
 
 ```php
 <?php
 // my-plugin.php
 
-function my_plugin_allowed_block_types( $allowed_block_types, $post ) {
-	if ( $post->post_type !== 'post' ) {
-		return $allowed_block_types;
+function filter_allowed_block_types_when_post_provided( $allowed_block_types, $editor_context ) {
+	if ( ! empty( $editor_context->post ) ) {
+		return array( 'core/paragraph', 'core/heading' );
 	}
-	return array( 'core/paragraph' );
+	return $allowed_block_types;
 }
 
-add_filter( 'allowed_block_types', 'my_plugin_allowed_block_types', 10, 2 );
+add_filter( 'allowed_block_types_all', 'filter_allowed_block_types_when_post_provided', 10, 2 );
 ```
 
 ## Managing block categories
 
-It is possible to filter the list of default block categories using the `block_categories` filter. You can do it on the server by implementing a function which returns a list of categories. It is going to be used during blocks registration and to group blocks in the inserter. You can also use the second provided param `$post` to generate a different list depending on the post's content.
+### `block_categories_all`
+
+_**Note:** Before WordPress 5.8 known as `block_categories`. In the case when you want to support older versions of WordPress you might need a way to detect which filter should be used – the deprecated one vs the new one. The recommended way to proceed is to check if the `WP_Block_Editor_Context` class exists._
+
+It is possible to filter the list of default block categories using the `block_categories_all` filter. You can do it on the server by implementing a function which returns a list of categories. It is going to be used during blocks registration and to group blocks in the inserter. You can also use the second provided param `$editor_context` to filter the based on its content.
 
 ```php
 <?php
 // my-plugin.php
 
-function my_plugin_block_categories( $categories, $post ) {
-	if ( $post->post_type !== 'post' ) {
-		return $categories;
-	}
-	return array_merge(
-		$categories,
-		array(
+function filter_block_categories_when_post_provided( $block_categories, $editor_context ) {
+	if ( ! empty( $editor_context->post ) ) {
+		array_push(
+			$block_categories,
 			array(
-				'slug' => 'my-category',
-				'title' => __( 'My category', 'my-plugin' ),
-				'icon'  => 'wordpress',
-			),
-		)
-	);
+				'slug'  => 'custom-category',
+				'title' => __( 'Custom Category', 'custom-plugin' ),
+				'icon'  => null,
+			)
+		);
+	}
+	return $block_categories;
 }
-add_filter( 'block_categories', 'my_plugin_block_categories', 10, 2 );
+
+add_filter( 'block_categories_all', 'filter_block_categories_when_post_provided', 10, 2 );
 ```
 
+### `wp.blocks.updateCategory`
+
 You can also display an icon with your block category by setting an `icon` attribute. The value can be the slug of a [WordPress Dashicon](https://developer.wordpress.org/resource/dashicons/).
 
 You can also set a custom icon in SVG format. To do so, the icon should be rendered and set on the frontend, so it can make use of WordPress SVG, allowing mobile compatibility and making the icon more accessible.

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

@@ -64,13 +64,51 @@ addFilter(
 
 ## Editor settings
 
-### `block_editor_settings`
+### `block_editor_settings_all`
+
+_**Note:** Before WordPress 5.8 known as `block_editor_settings`. In the case when you want to support older versions of WordPress you might need a way to detect which filter should be used – the deprecated one vs the new one. The recommended way to proceed is to check if the `WP_Block_Editor_Context` class exists._
 
 This is a PHP filter which is applied before sending settings to the WordPress block editor.
 
-You may find details about this filter [on its WordPress Code Reference page](https://developer.wordpress.org/reference/hooks/block_editor_settings/).
+You may find details about this filter [on its WordPress Code Reference page](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/).
+
+The filter will send any setting to the initialized Editor, which means any editor setting that is used to configure the editor at initialiation can be filtered by a PHP WordPress plugin before being sent.
+
+_Example:_
+
+```php
+<?php
+// my-plugin.php
+
+function filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) {
+	if ( ! empty( $editor_context->post ) ) {
+		$editor_settings['maxUploadFileSize'] = 12345;
+	}
+	return $editor_settings;
+}
+
+add_filter( 'block_editor_settings_all', 'filter_block_editor_settings_when_post_provided', 10, 2 );
+```
+
+#### `block_editor_rest_api_preload_paths`
+
+Filters the array of REST API paths that will be used to preloaded common data to use with the block editor.
+
+_Example:_
+
+```php
+<?php
+// my-plugin.php
 
-The filter will send any setting to the initialized Editor, which means any editor setting that is used to configure the editor at initialisation can be filtered by a PHP WordPress plugin before being sent.
+function filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) {
+	if ( ! empty( $editor_context->post ) ) {
+		array_push( $preload_paths, array( '/wp/v2/blocks', 'OPTIONS' ) );
+	}
+	return $preload_paths;
+}
+
+add_filter( 'block_editor_rest_api_preload_paths', 'filter_block_editor_rest_api_preload_paths_when_post_provided', 10, 2 );
+```
 
 ### Available default editor settings
 
@@ -88,9 +126,11 @@ If set to false the user will not be able to switch between visual and code edit
 
 ### Block Directory
 
-The Block Directory enables installing new block plugins from [WordPress.org.](https://wordpress.org/plugins/browse/block/) It can be disabled by removing the actions that enqueue it. In WordPress core, the function is `wp_enqueue_editor_block_directory_assets`, and Gutenberg uses `gutenberg_enqueue_block_editor_assets_block_directory`. To remove the feature, use [`remove_action`,](https://developer.wordpress.org/reference/functions/remove_action/) like this:
+The Block Directory enables installing new block plugins from [WordPress.org.](https://wordpress.org/plugins/browse/block/) It can be disabled by removing the actions that enqueue it. In WordPress core, the function is `wp_enqueue_editor_block_directory_assets`. To remove the feature, use [`remove_action`,](https://developer.wordpress.org/reference/functions/remove_action/) like this:
 
 ```php
+<?php
+// my-plugin.php
+
 remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_editor_block_directory_assets' );
-remove_action( 'enqueue_block_editor_assets', 'gutenberg_enqueue_block_editor_assets_block_directory' );
 ```