We have reached the first WordPress core release where the post editor is no longer the only screen that uses the block editor. In the middle of the development process, we found out that several WordPress hooks defined on the server depended on the $post object that isn’t present on the updated screen that lets users edit widgets using blocks. Therefore, we decided to deprecate some of the existing filters and introduce their context-aware replacements. This way, we ensure that we can continue iteratively enabling the block-based paradigm on different screens like the navigation editor screen by leveraging the new WP_Block_Editor_Context class that will receive more capabilities over time. There are also new methods introduced that allow code reuse for the functionality that needs to be shared between the screen that uses the block editor.
Related Trac ticket: #52920.
A class representing a current block editor context.
The expectation is that the block editor can have a different set of requirements on every screen where it is used. This class allows defining supporting settings that can be used with filters.
Example:
$post_editor_context = new WP_Block_Editor_Context( array( 'post' => get_post() ) );A new method that makes it possible to share default block categories.
Example:
print_r( get_default_block_categories() );A new method to handle better the list of allowed block types depending on the editor context.
Example:
print_r( get_allowed_block_types( $post_editor_context ) );Most of settings defined on the client in the @wordpress/block-editor package in store/defaults.js file are now available on the server with the new get_default_block_editor_settings method.
Example:
print_r( get_default_block_editor_settings() );A new method ensures that the editor settings can differ depending on the editor's context.
Example:
$post_editor_settings = array(
'richEditingEnabled' => user_can_richedit(),
);
print_r( get_block_editor_settings( $post_editor_settings, $post_editor_context ) );The logic that preloads common data used with the block editor by processing an array of REST API paths got abstracted in a new method.
Example:
$preload_paths = array(
'/',
'/wp/v2/types?context=edit',
);
block_editor_rest_api_preload( $preload_paths, $post_editor_context ) );Several existing block editor filters that depend on the $post object get deprecated:
allowed_block_typesblock_categoriesblock_editor_preload_pathsblock_editor_settings
New filters are introduced as their replacements that are context-aware.
Filters the allowed block types for all editor types, defaulting to true (all registered block types supported).
Note: Replaces the deprecated allowed_block_types filter.
Example:
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 $allowed_block_types;
}
add_filter( 'allowed_block_types_all', 'filter_allowed_block_types_when_post_provided', 10, 2 );Filters the default array of categories for block types.
Note: Replaces the deprecated block_categories filter.
Example:
function filter_block_categories_when_post_provided( $block_categories, $editor_context ) {
if ( ! empty( $editor_context->post ) ) {
array_push(
$block_categories,
array(
'slug' => 'custom-category',
'title' => __( 'Custom Category', 'custom-plugin' ),
'icon' => null,
)
);
}
return $block_categories;
}
add_filter( 'block_categories_all', 'filter_block_categories_when_post_provided', 10, 2 );Filters the array of REST API paths that will be used to preloaded common data to use with the block editor.
Note: Replaces the deprecated block_editor_preload_paths filter.
Example:
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 );Filters the settings to pass to the block editor for all editor type.
Note: Replaces the deprecated block_editor_settings filter.
Example:
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 );