Meta Box back compat and fall backs #3554

pento · 2017-11-20T05:41:05Z

Even after Gutenberg is merged into Core, and a plugin has upgraded all of its meta boxes to using Gutenberg APIs, those plugin will still need to register classic meta boxes, for backwards compatibility with the classic editor.

Changes

This PR makes a few changes along those lines.

Back Compat Meta Boxen

When registering a meta box, adding a '__back_compat_meta_box' => true arg to the $callback_args argument of add_meta_box() will cause Gutenberg to ignore that meta box in the meta box UI - it's assumed that a plugin developer who defines this arg will have registered a Gutenberg-specific UI for this meta box.

For example:

add_meta_box(
	'lol',
	'foo',
	function() {
		echo 'whee';
	},
	null,
	'normal',
	'high',
	array(
		'__back_compat_meta_box' => true,
		'__block_editor_compatible_meta_box' => true,
	)
);

Falling Back To The Classic Editor

If an unsupported meta box is detected while loading Gutenberg, we now redirect to the classic editor. Currently, this is any meta box that explicitly declares the __block_editor_compatible_meta_box arg as a false-y value.

A future iteration could check if a meta box relies on complex scripts which are unlikely to work in Gutenberg, and fall back.

Warning the End User

Ultimately, the end user should know when a plugin causes a fallback to the classic editor. The warning looks something like this:

This currently only shows when WP_DEBUG is enabled, though would eventually be enabled at all times.

It doesn't show for meta boxes that set the __back_compat_meta_box flag, and naturally wouldn't show for other meta boxes that don't trigger a fallback.

Code Note

Obviously, some of this code is kind of weird, and a little bit hacky, to hook into the existing meta box rendering scheme. gutenberg_intercept_meta_box_render() and gutenberg_override_meta_box_callback(), for example, will be reduced to some small changes to do_meta_boxes(), come merge time.

#952

…with Gutenberg, fall back to the classic editor.

…on to show as non-empty

…'re not rendered.

…allback

pento · 2017-11-23T00:57:59Z

This is ready for merge, we can iterate on it more as we determine reasons for fallback.

youknowriad · 2017-11-24T08:19:18Z

docs/meta-box.md

@@ -36,7 +70,7 @@ have to do, unless we want to move `createEditorInstance()` to fire in the foote
 or at some point after `admin_head`. With recent changes to editor bootstrapping
 this might now be possible. Test with ACF to make sure.

-### Redux and React Meta Box Management.
+### Redux and React Meta Box Management

 *The Redux store by default will hold all meta boxes as inactive*. When
 `INITIALIZE_META_BOX_STATE` comes in, the store will update any active meta box


Unrelated but we should add this file to the Gutenberg Handbook.

Good point, I didn't even notice that it wasn't there. 🙂 Added!

youknowriad · 2017-11-24T08:21:49Z

lib/meta-box-partial-page.php

+		foreach ( $contexts as $context => $priorities ) {
+			foreach ( $priorities as $priority => $boxes ) {
+				foreach ( $boxes as $id => $box ) {
+					if ( ! is_array( $wp_meta_boxes[ $post_type ][ $context ][ $priority ][ $id ]['args'] ) ) {


Can we replace $wp_meta_boxes[ $post_type ][ $context ][ $priority ][ $id ] by $box in this loop?

We can really only replace the first instance - $box is a copy of the array element, so modifications need to be applied to $wp_meta_boxes.

Too many JS in my head :)

youknowriad · 2017-11-24T08:23:10Z

lib/meta-box-partial-page.php

+
+	if ( isset( $box['args']['__back_compat_meta_box'] ) ) {
+		$block_compatible |= (bool) $box['args']['__back_compat_meta_box'];
+		unset( $box['args']['__back_compat_meta_box'] );


Just per curiosity, why do we unset these keys?

Copying the same pattern from Core - the meta box render function doesn't need to know about these keys.

youknowriad · 2017-11-24T08:24:42Z

lib/meta-box-partial-page.php

+ */
+function gutenberg_show_meta_box_warning( $callback ) {
+	// Only show the warning when WP_DEBUG is enabled.
+	if ( ! WP_DEBUG ) {


I wonder if we should not show it even in "prod" while we're on the plugin phase and introduce this change later. To encourage people to check their metaboxes?

I did this way while we're still working out the path for plugin devs to move their meta boxes to blocks - it doesn't seem fair to show a warning that the dev can't do anything to fix.

Once there are well documented upgrade paths, we can take away this check. Once it comes time to merge, we can evaluate how we want to merge it. It might even be valuable to have a "plugin x caused this fall back" message in prod, so users know what happened, and a "here are links to documentation and tutorials to upgrade your meta boxes" when WP_DEBUG is set, so plugin devs have the information they need.

youknowriad · 2017-11-24T08:29:38Z

On my testing I have ACF with some fields, I was expecting Gutenberg to redirect because by default all metaboxes are not compatible with gutenberg yet? I'm I wrong?

Also, I noticed this warning

The warning is hidden behind the Gutenberg UI (make sure to check the HTML output)

pento · 2017-11-27T03:30:04Z

On my testing I have ACF with some fields, I was expecting Gutenberg to redirect because by default all metaboxes are not compatible with gutenberg yet? I'm I wrong?

It currently only redirects if a meta box declares itself incompatible with Gutenberg - the idea is to have an opt-out system, combined with potentially detecting meta boxen that are incompatible.

Also, I noticed this warning

Nice catch, fixed!

codecov · 2017-11-27T03:48:09Z

Codecov Report

Merging #3554 into master will increase coverage by 1.13%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3554      +/-   ##
==========================================
+ Coverage    34.9%   36.03%   +1.13%     
==========================================
  Files         263      324      +61     
  Lines        6727     8453    +1726     
  Branches     1227     1571     +344     
==========================================
+ Hits         2348     3046     +698     
- Misses       3694     4564     +870     
- Partials      685      843     +158

Impacted Files	Coverage Δ
blocks/library/shortcode/index.js	`33.33% <0%> (-6.67%)`	⬇️
blocks/library/heading/index.js	`21.62% <0%> (-3.38%)`	⬇️
blocks/library/paragraph/index.js	`25.8% <0%> (-3.37%)`	⬇️
blocks/api/validation.js	`93.54% <0%> (-1.62%)`	⬇️
blocks/library/html/index.js	`15.78% <0%> (-0.88%)`	⬇️
blocks/library/more/index.js	`21.42% <0%> (-0.8%)`	⬇️
blocks/library/list/index.js	`6.2% <0%> (-0.7%)`	⬇️
editor/components/inserter/menu.js	`86.88% <0%> (-0.44%)`	⬇️
editor/selectors.js	`92.83% <0%> (-0.29%)`	⬇️
components/popover/index.js	`84.61% <0%> (-0.15%)`	⬇️
... and 85 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1709207...0b22b58. Read the comment docs.

youknowriad

Thanks for working on this. Let's get this in. I personally prefer it to be opt-in by let's try this and see if we should revisit.

aduth · 2017-11-27T17:08:11Z

docs/meta-box.md

+
+```php
+add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
+    null, 'normal', 'high',


Mixed whitespace, tabs and spaces.

Noice. #3684.

aduth · 2017-11-27T17:08:41Z

lib/register.php

+			}
+
+			// Incompatible meta boxes require an immediate redirect to the classic editor.
+			if ( $incompatible_meta_box ) {


Could we not perform the redirect server-side here?

With the current code, no. gutenberg_collect_meta_box_data() happens in the admin_head action, well after HTML has started being sent.

youknowriad · 2018-01-12T15:02:18Z

lib/register.php

@@ -219,10 +219,40 @@ function gutenberg_collect_meta_box_data() {

 	// If the meta box should be empty set to false.
 	foreach ( $locations as $location ) {
-		if ( isset( $_meta_boxes_copy[ $post->post_type ][ $location ] ) && gutenberg_is_meta_box_empty( $_meta_boxes_copy, $location, $post->post_type ) ) {
+		if ( gutenberg_is_meta_box_empty( $_meta_boxes_copy, $location, $post->post_type ) ) {


This call is always returning false for "side" meta boxes because the array doesn't have a "side" key even if I do have a side meta box? Any idea how to fix this @pento

Nevermind, I might have had a weird setup at that moment. It's working as expected right now.

pento added 2 commits November 20, 2017 15:59

When a meta box is registered that doesn't declare itself compatible …

95465e6

…with Gutenberg, fall back to the classic editor.

Fix some linting errors

557bb01

pento added [Feature] Meta Boxes A draggable box shown on the post editing screen [Type] Enhancement A suggestion for improvement. labels Nov 20, 2017

pento added this to the Beta 1.8 milestone Nov 20, 2017

pento self-assigned this Nov 20, 2017

pento added 10 commits November 22, 2017 15:32

Add a test for back compat meta boxes not causing the meta box locati…

996faed

…on to show as non-empty

Filter back compat meta boxes out of the meta box array, so that they…

08c322a

…'re not rendered.

Incorrect variable name

8a80393

Fix a phpunit error.

1b1cd73

Allow meta boxes to marke themselves incompatible with Gutenberg

f030f01

Update the meta box documentation to fit the new functionality.

305fb48

Don't show the meta box warning on meta boxes that didn't cause the f…

91c06fc

…allback

Revert some previous changes to gutenberg_is_meta_box_empty()

21a2375

Don't show the fallback warning if the meta box is just for back compat.

b38729d

Fix some linting errors

a160c28

pento requested review from youknowriad, mtias, aduth and BE-Webdesign November 23, 2017 00:57

youknowriad reviewed Nov 24, 2017

View reviewed changes

Fix a PHP warning when a meta box location isn't set

fdae2d4

Add the meta boxes docs to the Handbook

0b22b58

youknowriad approved these changes Nov 27, 2017

View reviewed changes

pento merged commit 9864a60 into master Nov 27, 2017

pento deleted the add/meta-box-fallback branch November 27, 2017 08:30

aduth reviewed Nov 27, 2017

View reviewed changes

pento mentioned this pull request Nov 29, 2017

Supporting Metaboxes #952

Closed

jeremyfelt mentioned this pull request Dec 7, 2017

Don't intercept rendering of removed meta boxes #3856

Merged

3 tasks

kevinwhoffman mentioned this pull request Dec 10, 2017

Determine how plugin conflicts are handled and communicated #3902

Closed

youknowriad reviewed Jan 12, 2018

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Meta Box back compat and fall backs #3554

Meta Box back compat and fall backs #3554

pento commented Nov 20, 2017 •

edited

pento commented Nov 23, 2017

youknowriad Nov 24, 2017

pento Nov 27, 2017

youknowriad Nov 24, 2017

pento Nov 27, 2017

youknowriad Nov 27, 2017

youknowriad Nov 24, 2017

pento Nov 27, 2017

youknowriad Nov 24, 2017

pento Nov 27, 2017

youknowriad commented Nov 24, 2017

pento commented Nov 27, 2017

codecov bot commented Nov 27, 2017 •

edited

youknowriad left a comment

aduth Nov 27, 2017

pento Nov 28, 2017

aduth Nov 27, 2017

pento Nov 28, 2017

youknowriad Jan 12, 2018

youknowriad Jan 25, 2018

Meta Box back compat and fall backs #3554

Meta Box back compat and fall backs #3554

Conversation

pento commented Nov 20, 2017 • edited

Changes

Back Compat Meta Boxen

Falling Back To The Classic Editor

Warning the End User

Code Note

pento commented Nov 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad commented Nov 24, 2017

pento commented Nov 27, 2017

codecov bot commented Nov 27, 2017 • edited

Codecov Report

youknowriad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pento commented Nov 20, 2017 •

edited

codecov bot commented Nov 27, 2017 •

edited