WordPress 5.8 is the first core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. release where the post editor is no longer the only admin (and super admin) screen that uses the block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. The updated widgets editor screen will also support blocks.
During the development process, we found several WordPress hooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. defined on the server depended on the $post
object that is not present on the widgets screen. So, we decided to deprecate some of the existing filters and introduce context-aware replacements.
These updates enable us to iteratively bring the block-based paradigm to different screens. For example, the navigation editor screen can leverage the new WP_Block_Editor_Context
class and 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 An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket Created for both bug reports and feature development on the bug tracker.: #52920.
Class
WP_Block_Editor_Context
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() ) );
Functions
get_default_block_categories
A new method that makes it possible to share default block categories.
Example:
print_r( get_default_block_categories() );
get_allowed_block_types
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 ) );
get_default_block_editor_settings
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() );
get_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 ) );
block_editor_rest_api_preload
The logic that preloads common data used with the block editor by processing an array of REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/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 ) );
Filters
Several existing block editor filters that depend on the $post
object get deprecated:
allowed_block_types
block_categories
block_editor_preload_paths
block_editor_settings
New filters are introduced as their replacements that are context-aware.
allowed_block_types_all
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 Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..
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 );
block_categories_all
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 );
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.
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 );
block_editor_settings_all
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 );
Supporting older versions of WordPress
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.
Example:
if ( class_exists( 'WP_Block_Editor_Context
' ) ) {
add_filter( 'block_editor_settings_all', 'filter_block_editor_settings_compat', 10, 2 );
} else {
add_filter( 'block_editor_settings', 'filter_block_editor_settings_compat', 10, 2 );
}
#5-8, #dev-notes, #gutenberg