Meta Box Compatibility Flags

The new 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 has the ability to load metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. boxes, to help plugins transition to the new GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ platform. This compatibility functionality works fairly seamlessly with basic meta boxes, but more complex uses may require modification, particularly those that make heavy use of DOM-dependent JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/..

To help ensure end users have the best possible experience, there are two flags you can set when adding a meta box, which WordPress will use when determining when to load the block editor, or to fall back to the classic editor.

Flags

__block_editor_compatible_meta_box

This flag lets you set whether the meta box works in the block editor or not. Setting it to true signifies that the you’ve confirmed that the meta box works in the block editor, setting it to false signifies that it doesn’t. If the flag isn’t set, then WordPress 5.0 will assume that the meta box does work in the block editor.

__back_compat_meta_box

This flag lets you set whether the meta box is intended to be used in the block editor, or if it has been replaced by block-based functionality. Setting it to true signifies that this meta box should only be loaded in the classic editor interface, and the block editor should not display it. Setting it to false signifies that this meta box is intended to be loaded in the block editor. If the flag isn’t set, then WordPress 5.0 will assume that the meta box is intended to be loaded in the block editor.

Usage

These flags are used by passing them in the $args parameter of add_meta_box(), like so:

add_meta_box(
	'my-meta-box-id',
	__( 'My Meta Box', 'textdomain' ),
	'my_meta_box_callback',
	'post',
	'advanced',
	'default',
	array(
		'__block_editor_compatible_meta_box' => true,
		'__back_compat_meta_box'             => false,
	)
);

Fallback Warnings

WordPress 5.0 also contains a developer preview of a fallback warning. If you set WP_DEBUG to true, then create a meta box with __block_editor_compatible_meta_box set to false, and __back_compat_meta_box either undefined, or set to false as well, this warning will show in the classic editor.

This warning is currently intended to be a developer preview, hence why it’s hidden behind the WP_DEBUG flag, and requires a particular combination of the compatibility flags to be set. The wording and appearance of the warning will likely change in future WordPress versions, but it’s ultimately intended to help end users identify which pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party is responsible for a meta box.

If you register your meta box with the __back_compat_meta_box set to true, then this warning will never be displayed with your meta box, now, or in future WordPress releases.

Future Changes

Future versions of WordPress may change how they behave when these flags are set. For example, WordPress 5.0 will silently fall back to the classic interface when an incompatible meta box is encountered. Classic editor code will likely be moved to the Classic Editor plugin in the future, however, so those future WordPress versions would require the Classic Editor plugin to be installed before it could automatically fall back. Any such changes would be posted well in advance, to ensure there’s plenty of warning for testing changes.

#5-0, #dev-notes