Block Editor API Changes to Support Multiple Admin Screens in WP 5.8


WordPress 5.8 is the first coreCore 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 adminadmin (and super admin) screen that uses the blockBlock 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 hooksHooks 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 TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket 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 APIREST 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 filterFilter 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