Gutenberg: Introduce 'block-editor' post type supports attribute for custom post types with custom controllers

[mathetos]

Issue Overview

This issue is primarily a Core issue for consideration when Gutenberg gets incorporated into WordPress Core.

Custom Post Types should have to declare Gutenberg Support. Currently the "Gutenberg" link is added by default to all post types. Clicking on that link with a custom post type currently takes the user to an error page saying: "No route was found matching the URL and request method" -- a pretty terrible user experience.

Expected Behavior

The "Gutenberg" link should only appear on post types that have declared support for Gutenberg. If that is not there, then the post type edit screen will be loaded with the now current traditional edit screen.

Possible Solution

Add a new "supports" option when post types are registered, like so:

$args = array(
        'supports' => array( 'gutenberg', 'author', 'thumbnail', 'excerpt', 'comments' )
    );

The default for "supports" should NOT include 'gutenberg' so that it has to be intentionally declared since most post types that exist today will fail as-is.

[steveangstrom]

I agree, but I suggest that a descriptive declaration such as "block-editor" is more applicable as "gutenberg" is a project name and stands out amid the other declarations.

[mathetos]

Good point @steveangstrom

Most likely we'll want to make sure "block-editor" overrides "editor" if both are declared accidentally as well.

[BE-Webdesign]

Custom Post Types should have to declare Gutenberg Support.

Pretty sure that is the intent of the block editor ( Gutenberg ), even though it might not be clear because the link is added. A lot of the WordPress end of things have yet to be ironed out/polished as the interactions within Gutenberg are the main focus of development for now. Polish, will be coming soonish!

[kevinwhoffman]

@mathetos I do agree this would avoid some of the most complicated compatibility issues, but in the end I think it leads us toward a tale of two WP Admins.

We need to think through the side effects of declaring support for one type of editor or another. Gutenberg, as it exists today, is a full-screen replacement, which means toggling support for it affects not just the editor, but also what hooks are available and how meta boxes work. The internals and appearance of the entire sidebar change as well.

By _not_ declaring support for Gutenberg, we preserve the interfaces that exist today, but at what cost? Here are some of the harmful side effects:

• This path would lead us towards a fractured admin experience with no foreseeable point of convergence. Simple actions like adding a title, publishing a post, or managing revisions shouldn't change from one post type to the next based on whether a developer has declared Gutenberg support.
• If the only way to ensure that existing interfaces continue to function is to avoid registering support for Gutenberg, then we prevent a significant portion of the audience from ever seeing Gutenberg on their existing sites.
• This decision would also increase the burden on plugin developers who now have to ensure their meta boxes/blocks work both in "legacy" mode and within Gutenberg. The burden is not as heavy on plugins that define their own post types, but for plugins that add meta boxes to existing post types, they would now have to support a dual code base.

I've been mulling over a solution like this for a few months, but ultimately the scope creep of the editor out into the edit screen means that declaring support for one editor or another isn't as straightforward as it sounds. Instead it seems to replace a major problem with several smaller ones.

[mathetos]

This issue is made with the assumption that Gutenberg will be introduced into Core. This issue isn't creating a problem, its helping navigate a way forward in light of the current trajectory of the project.

Generally speaking, I only see a few options for what that might look like currently:

1. Gutenberg changes drastically to not encroach throughout the edit screen -- which seems to be your preference @kevinwhoffman
2. Gutenberg takes over all post type screens by default, then anyone building a CPT has to do all kinds of somersaults to work around it or with it -- not a fun idea.
3. Have the authors of post types make an intentional decision to support Gutenberg for their post type or not. Making that intentional decision naturally means the CPT author will be ready to deal with the hooks available and how meta data works for their post type with Gutenberg.

The third option -- which I'm suggesting -- seems the most reasonable as well as backward compatible. That is of course unless something drastic changes between now and when Gutenberg is ready for Core integration, which might be the case; you never know.

[kevinwhoffman]

I see two major challenges facing Gutenberg, the first based on the past and the second on the future:

1. Don't break existing sites.
2. Create a consistent admin experience moving forward.

Declaring Gutenberg support for a post type solves the first goal, but it creates two separate admin experiences going forward. This is what I mean by solving one problem by introducing another.

Have the authors of post types make an intentional decision to support Gutenberg for their post type or not. Making that intentional decision naturally means the CPT author will be ready to deal with the hooks available and how meta data works for their post type with Gutenberg.

This is great for the author of the post type, but any other developer attempting to extend the functionality of the post type does not have knowledge of the editor type and therefore would have to prepare their plugin for both legacy and Gutenberg scenarios. Many plugins don't define post types at all as their entire purpose is to extend any post type's functionality.

For example's sake, let's say I'm a modern developer and I convert my plugin's shortcode to a Gutenberg block like many other contributors are suggesting. But then I find out that most of my existing customers are using this legacy interface. Now any future development on my plugin has to include maintenance and updates for both new and old implementations with no plan for future convergence.

Imagine writing documentation for your plugin's shortcode-turned-block two completely different ways for Gutenberg and legacy users, and expecting the user to know which is which. Or having to ask users whether they are using the Gutenberg interface or the legacy interface in order to properly debug an issue. Or even worse, what if one user has multiple post types on their site, some of which use Gutenberg and others which use legacy mode? Now the same customer has to learn how to use your plugin two different ways by inserting a shortcode in one post type and a block in another.

[mattiman2]

@kevinwhoffman that's a good summary of the main challenges. The thing is though, that the problem of breaking existing sites is entirely created by the Gutenberg project itself wanting to move forward so quickly and having such a large scope (especially forcing meta boxes into "legacy", whatever that will mean). Creating a constant admin experience is important of course. But not breaking half of all existing Wordpress sites would seem more important at the moment.

[mtias]

A block-editor might be a good property to declare. @pento any thoughts? Might be similar to some of the fallback meta-box handling.

Worth noting gutenberg already handles when a post type doesn't support editor.

[pento]

I'm not wild about the opt-in option for CPTs. I like the editor check, and I'd be cool with a block-editor CPT support flag that defaults to true, allowing CPTs to explicitly opt out of Gutenberg.

I'm also interested in ways we can detect whether a particular CPT is going to work in Gutenberg, similar to meta boxes.

I'd like to see some examples of CPT usage that declares editor support, but breaks in Gutenberg.

[BE-Webdesign]

I think if we can get more and more meta boxes to work, this problem sort of goes away. The main breakage I see is all meta box related. Originally I was more on the opt-in train of thought, but after seeing how things are playing out, I think opt-out would be ideal, if we can minimize the problems surrounding meta boxes.

[SilentComics]

I too believe opt-out would be a better approach. CPTs should start at least with the same editing options than regular posts. You might want to opt out if the CPT is layout-specific though, but their aim is often only taxonomies.
In an ideal world CPTs should have Gutenberg's layout-editing capacities. But also let them override or add layout blocks if needed.

[espiat]

Will be there a possibility for theme and plugin authors to label the plugin as "Gutenberg-ready" in the repository? If yes, is the information viewable in the plugin repo api or in the frontend like "Last updated: ", "Tested up to: ", ...?

[jiffymac]

@BE-Webdesign would it not make sense to have opt-in until the Meta Box issue is solved then move to opt-out. That solves both issues of not breaking things and moving towards a consistent admin experience.

[DrewAPicture]

It seems that one part of the argument that's starkly missing from the discussion here is the case where a custom post type doesn't even use the editor, for instance. Maybe it's just a collection of custom meta boxes or even a custom editing experience. That would be a case where i would want to explicitly exclude a custom post type from Gutenberg "support".

It's one thing to replace the experience of editing written or embedded content in the editor with editing written or embedded content in Gutenberg, it's another entirely to replace what could be a completely asynchronous, non-linear editing experience with something like Gutenberg. Apples to oranges is probably OK, apples to potatoes, probably not so much.

What if anything is going to be the current approach on allowing (or disallowing) post types to "opt-in" to Gutenberg/block-editor support?

[pento]

CPTs don't opt-in to Gutenberg support, they opt-out. Currently, that's by declaring that they don't support editor. We discussed having a separate block-editor flag, I think the primary use case for that would be declaring that the CPT supports Classic, but not Gutenberg.

I don't mind the option of 5.0 landing with the current behaviour, that CPTs will use Classic if they don't support editor. We can figure out a way for these CPTs to use Gutenberg in a later release.

CPTs that provide a custom interface are not affected by Gutenberg. The replace_editor filter added in WordPress 4.9 will continue to be respected, and plugins that override the edit screen earlier in the process (ACF being a notable example here) will continue to be able to override it.

[DrewAPicture]

Noted. For what it's worth, this is the first time I've heard of the replace_editor hook ;-)

[kevinwhoffman]

@pento Can you clarify when you would use the replace_editor filter versus just not declaring support for editor when registering the post type?

[pento]

Sure, replace_editor is for when you want to provide an entirely custom editing interface for the CPT. For example, this is how Gutenberg uses it.

The current _Core_ behaviour when your CPT removes editor support is to load the editor interface, without the content editor.

For 5.0, I was considering the option of having CPTs that remove editor to automatically fall back to Classic, where their current Core behaviour would be maintained: the content editor wouldn't show. This fall back would potentially change in future WordPress releases, if we add the ability for the block editor to be loaded without the block interface. The CPT may then only fall back to Classic if it has an incompatible meta box, or if the Classic Editor plugin is installed.

[kevinwhoffman]

For 5.0, I was considering the option of having CPTs that remove editor to automatically fall back to Classic, where their current Core behaviour would be maintained: the content editor wouldn't show.

For CPTs that do not declare editor support, I think you are right to maintain the existing behavior through 5.0 (show the classic edit screen without TinyMCE editor). Many plugins use CPTs to house user experiences that are critical to their functionality. These tend to be the most complex pieces of functionality, such as form-building, that are the most difficult and time-consuming to map to Gutenberg. This means they're least likely to be ported to blocks when 5.0 drops.

In comparison, shortcodes and widgets are easier to blockify, and based on observation, that is where most plugins are focusing their first steps into Gutenberg.

[jasonbahl]

So, I'm working on a project where I want to use a Gutenberg layout, with all fixed/locked blocks that store in postmeta.

It took me a while to realize that Gutenberg wasn't showing up because I didn't have editor support added. It felt natural to _not_ register "editor" support, as my post_type doesn't make use of anything stored in post_content. But that caused the Gutenberg interface to _not_ display.

Just throwing out there that "editor" support is (in my opinion) tightly coupled to post_content, but Gutenberg isn't necessarily tightly coupled to post_content.

So I'd suggest there be an additional supports flag for block-editor or gutenberg or whatever. Something that's more explicit.

That way, other plugins that assume editor is coupled with post_content can continue making that assumption without being disrupted by Gutenberg.

[jasonbahl]

^ perhaps I'm mistaken. Even blocks that store to postmeta will _also_ store some content in the post_content for Gutenberg, eh? So I suppose Gutenberg is always tightly coupled with post_content, eh?

[jasonbahl]

^ I'm correcting myself again. In my case, I have a post_type that pulls data in from a 3rd party API and the data _should not_ be mutable in the wp-admin, but it should be viewable. So, I will be using Gutenblocks to display read-only data. So, no data will be stored in post_content at all, but I still want Gutenberg as the interface.

So, Gutenberg isn't necessarily tightly coupled with post_content, where "editor" is.

Still vote to have a more explicit "supports" declaration for Gutenberg. Possibly with some fallback to editor. But more explicit is better in my opinion.

[danielbachhuber]

Related #3462

[mathetos]

This is an old issue (I probably was thinking too far ahead when I wrote it), and we've had a lot of discussion and a TON of development has happened since this all started. So, how about I summarize.

Based on @pento s comment here :

I don't mind the option of 5.0 landing with the current behaviour, that CPTs will use Classic if they don't support editor. We can figure out a way for these CPTs to use Gutenberg in a later release.

CPTs that provide a custom interface are not affected by Gutenberg. The replace_editor filter added in WordPress 4.9 will continue to be respected, and plugins that override the edit screen earlier in the process (ACF being a notable example here) will continue to be able to override it.

It sounds like this is the plan for merging into Core:

1. There will be no block-editor flag for CPTs
2. If I register a CPT and I want to support the editor at all, I'm going to get Gutenberg
3. If I register a CPT and I want to customize everything about the edit screen, I'll have the option to use the replace_editor filter just like Gutenberg does.

If I've got that right, here's a few examples to consider:

ACF and other Page Builders
Already mentioned, but obviously they'll be using replace_editor just like Gutenberg does.

Most plugins that use Shortcodes
They'll most likely create blocks, or update their docs to highlight the shortcode block. They'll be fine.

Freelancers/Agencies that build CPTs in their sleep
If they want to use something like CMB2 or whatnot, they can set editor support to false, and create all their metaboxes including the main content editor with the classic TinyMCE editor.

Or they need to learn how to create a trimmed down Gutenberg block experience. This is made a bit easier with Gutenberg features like this one, and ideally this one if it gets addressed.

But the ideal experience in a post-Gutenberg-merge world is that the editor always means Gutenberg, so it's kind of all or nothing.

Is that the gist @pento ?

[pento]

Thanks for the summary, @mathetos. As @danielbachhuber's comment suggests, there are a few inter-related issues.

I think a block-editor flag would be useful as a transition tool, for a couple of different uses cases.

• For a CPT that works in classic, but not the block editor, they would set the block-editor flag to false, to automatically fall back to classic.
• For a CPT that works in the block editor, but doesn't have show_in_rest set, or uses a custom endpoint (as described in #3462), they can explicitly define block-editor support, which will cause the block editor to either default that CPT's show_in_rest setting to true, or assume that the custom endpoint exposes post data in the same way that a generated CPT endpoint does.
• For CPTs that neither define show_in_rest, nor block-editor, fall back to classic.

It's important to note that that the behaviour of falling back to classic would only be guaranteed for WordPress 5.0: a future release _will_ change this behaviour: CPTs that don't explicitly opt out will likely start loading in the block editor, and those that do opt out will potentially show a "you need to install the Classic Editor plugin" message. I would expect CPTs that use replace_editor to continue to function normally, though there may be some Core libraries that will be moved to the Classic Editor plugin at some later date, so simply reproducing the classic interface is not a permanent solution. 🙂

Obviously, these changes won't happen without being appropriately announced, but you should be planning on updating your code to support the block editor where you can, and rolling out the Classic Editor plugin where you cannot.

We definitely don't want to leave folks with a transition process that they don't understand, or to cut support off prematurely. But it does need to be explicitly clear that everyone will eventually need to transition to either supporting the block editor, or requiring the classic editor.

[maddisondesigns]

@pento Is the Classic Editor plugin going to be updated so that it's more flexible? At the moment it only provides a simple checkbox that basically turns off Gutenberg, or provides an Edit (Classic) link under the Page/Post title.

Ideally it would be good to be able to select which post type uses Gutenberg and which doesn't. i.e. Display a separate checkbox for every CPT on the site and also for one Pages and one for Posts. What if someone is happy for their site to use Gutenberg on Posts but want the classic editor on Pages and on their CPT? Having Edit (Classic) link is one thing, but if someone wants to use both types of editor (for whatever reason), having everything default to Gutenberg is going to be really frustrating for them.

[pento]

@maddisondesigns: No, adding that kind of UI isn't planned for the Classic Editor plugin. I understand that people may want to have more advanced UI control, we can certainly add any filters such a plugin would need to be able to create that.

[greatislander]

@pento Following up on your comment:

I think a block-editor flag would be useful as a transition tool, for a couple of different uses cases.

Is there anything I can do to help move this forward? I expect a ticket in WordPress Core Trac to introduce the new flag would be needed; then corresponding code to enable Gutenberg for CPTs with the 'supports' => [ 'block-editor' ]?

[danielbachhuber]

@greatislander Let's land a PR here (with corresponding unit tests), and then use it as the basis of the core ticket we open. Ultimately, this won't land in core until WP 5.0

[greatislander]

@danielbachhuber I'll try to take a look at this soon.

[danielbachhuber]

assume that the custom endpoint exposes post data in the same way that a generated CPT endpoint does.

8682 is related because it's another implicit expectation of functionality that may or may not be available on non-wp/v2 routes.

[mtias]

What's the status of this one?

[greatislander]

Haven't had any bandwidth to work on this (I was hoping to).

[ajitbohra]

https://make.wordpress.org/core/2018/10/30/block-editor-filters/

Plugins can define support for block editor using editor in support or using add_post_type_supports()

In WordPress 5.0, use_block_editor_for_post, and use_block_editor_for_post_type are available. You can use them like so:

function my_post_filter( $use_block_editor, $post ) {
    $author = get_userdata( $post->post_author );
    if ( 'pento' === $author->user_login ) {
        return (bool) random_int( 0, 1 );
    }

    return $use_block_editor;
}
add_filter( 'use_block_editor_for_post', 'my_post_filter', 10, 2 );

function my_post_type_filter( $use_block_editor, $post_type ) {
    if ( 'my_mystical_post_type' === $post_type ) {
        return false;
    }

    return $use_block_editor;
}
add_filter( 'use_block_editor_for_post_type', 'my_post_type_filter', 10, 2 );

[youknowriad]

Thanks for the discussions.

5.0 is already out and we have alternative ways to declare/disable Gutenberg support.

Long-term, all CPT will use the block editor (with its different options, with/without content area, with a frozen template...). I don't think it makes sense to add "block-editor" support key if the block editor is the only editor available in WordPress by default.

[covertninesam]

Okay, I'm thinking of a directory-style website, where each entry in the directory is a custom-type post. What is the ideal way to configure the admin-side editor without simply disabling the block-editor? Frankly, I _absolutely_ think it should be optional on custom post types, but maybe I'm missing something.