Provide better guidance for users looking to test FSE themes

[desrosj]

If a user activates a Full Site Editing theme and the Gutenberg plugin is not active, the front end of their website will break. The actual experience depends on the theme itself, but it consists of either:

• Blank white screen.
• A white screen with an unstyled notice saying the theme was built for the full site editing feature.
• A styled notice saying the theme was built for the full site editing feature.

Before activating the theme, it's not clear to the user that the Gutenberg plugin is required, or that their site will be unusable without it. In the traditional theme experience, the site's content is at least visible when activating a new theme, so this new experience is a bit different.

If Gutenberg is active with a FSE theme, there is also nothing stopping the user from deactivating the plugin. This scenario would result in the same problem as the one detailed above.

This ticket is to explore what can be done to help educate the user about this, and how Core can protect against this.

[desrosj]

Some suggestions so far:

• Hide FSE themes from the Add New Theme page when a user does not have Gutenberg active.
• Display a notice to the user when selecting the Full Site Editing feature filter on the theme page.
• Prevent a site owner from activating a FSE theme when Gutenberg is not active (potentially with a "activate anyway" button).
• Prevent a site owner from deactivating Gutenberg when an FSE theme is active.
• Providing links to documentation on the devhub/helphub.

Some of these may be appropriate to implement in Core or the Gutenberg plugin.

I'll be looking into the lowest effort/highest impact changes that can be made after beta 2 is packaged later today.

[knutsp]

Front end error messages is as undesirable as a white screen. Another suggestion to add

• Activate default theme and inform admin if Gutenberg is deactivated anyway

Will FSE themes be available to list from directory or install from file, for WP < 5.8, with or without Gutenberg? Should some limitations be backported to at least 5.7 branch?

[desrosj]

53410.diff​ is a proof of concept that adds a check for the full-site-editing tag in the theme's style.css file. With this patch:

• A user can preview the theme in the Customizer, but they are not allowed to activate it unless Gutenberg is active.
• Clicking activate in the admin throws a WP_Error displays on a wp_die() screen.

The error message displayed is very basic right now, but I envisioned an "Activate anyway" button, and potentially linking out to a page on .org explaining traditional themes vs. FSE themes.

plugin-screen.png​ shows what I have in mind for the plugin screen. Deactivating Gutenberg will not be blocked, but a notice can be added to point out that the plugin is required for the current theme. This could and should probably be added to the plugin itself (the action hooks needed are already present in Core).

[marybaum]

Replying to desrosj:

Okey dokey.

Here's some updated text for the strings in the screenshots and patches below. If our style really requires the removal of hyphens in compound modifiers, go for it — I can't yet make myself do that.

There are two versions of the message about FSE themes:

"This theme is built to help test ..." and "This theme requires Gutenberg ..."

With the Block-Based Bosco theme, I took a look down the road to a time when FSE is less experimental, and wrote the message accordingly. For now, the message should take the language about FSE being experimental.

The first and last messages are identical, so the edits are identical. Other edits give us a chance to let folx know that playing with carries risk.

So ....

—————

Old: This theme was built for the WordPress experimental full-site editing feature. You need to install and activate the Gutenberg plugin to make it work.

New: This theme is built to test Full-Site Editing, an experimental WordPress feature. It will only work if you install and activate the Gutenberg plugin.

———————

Old: This theme requires the Gutenberg plugin installed. Please visit your dashboard and follow the instructions on the notification displayed to enable the plugin and the Full Site Editing experiment.

New: This theme is built for an experimental feature called Full-Site Editing and requires the Gutenberg plugin, which must be both installed and active.

To help test that feature, please visit your dashboard and follow the instructions for enabling Gutenberg.
———————--

Old: Block-Based Bosco is a Full-Site Editing theme, which requires the Gutenberg plugin.

New: Block-Based Bosco is a Full-Site Editing theme that required the Gutenberg plugin.

(Note: This is copy for down the road. For now, the theme should carry one of the experimental-use messages.)
———--

Old: Gutenberg is required for your theme to work correctly. Deactivating is not recommended.

New: Gutenberg is required for your theme to work correctly. Deactivating it could disable parts of your site.

————

Old: This theme was built for the WordPress experimental full-site editing feature. You need to install and activate the Gutenberg plugin to make it work.

New: See NEW above.

53410.diff​ is a proof of concept that adds a check for the full-site-editing tag in the theme's style.css file. With this patch:

• A user can preview the theme in the Customizer, but they are not allowed to activate it unless Gutenberg is active.
• Clicking activate in the admin throws a WP_Error displays on a wp_die() screen.

The error message displayed is very basic right now, but I envisioned an "Activate anyway" button, and potentially linking out to a page on .org explaining traditional themes vs. FSE themes.

plugin-screen.png​ shows what I have in mind for the plugin screen. Deactivating Gutenberg will not be blocked, but a notice can be added to point out that the plugin is required for the current theme. This could and should probably be added to the plugin itself (the action hooks needed are already present in Core).

[desrosj]

Thanks for that review @marybaum. Sorry if any of the information I've shared was misleading, but we're not looking to standardize the errors shown on the front end as they're defined on a per theme basis. It would be great for there to be one, consistent notice, but that's outside the scope of this ticket. We're looking to add a protective measure to avoid encountering those notices when possible.

Here we're mainly concerned with the warnings shown in activate-error.png​ and plugin-screen.png​.

I've been thinking it over a bit and and discussed with @chanthaboune. For the first one, we're going with "Error: This theme (TT1 Blocks) uses Full Site Editing, which requires the Gutenberg plugin to be activated."

New: Gutenberg is required for your theme to work correctly. Deactivating it could disable parts of your site.

There are some other strings in Core using "your" but it feels a bit strange to me in general as the user viewing the notice may not always be the person that actually owns the site. The phrasing we've decided on for this warning is "This plugin is required for the active theme to work correctly. Deactivating is not recommended." I've opened ​a PR on GitHub for this one, as the best place to put this is in the plugin itself.

[desrosj]

In 51193:

Themes: Prevent a Full Site Editing theme from being activated when Gutenberg is not active.

When a theme that uses the Full Site Editing feature is activated and the Gutenberg plugin is not present, the site will currently show a text notice on the front end. The user is not made aware of this unless they visit the front end of their site.

This adds a check that will prevent a theme from being activated when the full-site-editing tag is present in the theme’s style.css header and the Gutenberg plugin is not active to prevent this scenario.

These checks can be removed once Full Site Editing is completely merged into Core.

Props desrosj, marybaum, chanthaboune.
See #53410.

Trac ticket: https://core.trac.wordpress.org/ticket/53410

[peterwilsoncc]

[51193] prevents sites with Gutenberg enabled as an mu-plugin from using FSE themes, as the is_plugin_active( 'gutenberg/gutenberg.php' ) returns false if that is the case.

In ​PR1410 I've replaced the check with ! function_exists( 'gutenberg_is_fse_theme' ) as that appears to be a likely function to move to core once FSE is available in WordPress.

@noisysocks has signed off on the PR, the tests are passing so I am going to commit it.

cc @desrosj

[peterwilsoncc]

In 51197:

Themes: Improve Gutenberg check before activating an FSE theme.

Account for sites enabling Gutenberg as an mu-plugin when determining whether full-site-editing themes can be enabled. This replaces the check the plugin is active with a check whether the function gutenberg_is_fse_theme() is defined.

Follow up to [51193].

Props noisysocks, peterwilsoncc, SergeyBiryukov.
See #53410.

https://core.trac.wordpress.org/changeset/51197

[desrosj]

I'm going to close this out. The upstream PR is where the rest should be addressed.

[aristath]

This is extremely disruptive... I understand why we're doing it, but some block themes include a script that urges users to activate Gutenberg, with a 1-click install & activation step (using the script from ​https://github.com/WordPress/theme-experiments/tree/master/require-gutenberg
Could we do something similar here?
Throwing an error in this fashion is scary to many users and gives the impression that themes are broken, which is far from true.
Maybe we should guide users instead of saying something went wrong? We could add a button that says "Install Gutenberg", linking to wp-admin/update.php?action=install-plugin&plugin=gutenbergt&_wpnonce={$nonce}? This way users would at least understand that using this theme is not prohibited, they just need to take an extra step.

[kafleg]

Totally agreed with @aristath

What about making automatically download and activate the Gutenberg plugin if the FSE theme is installed?

[poena]

I don't think the plugin should be activated without user action, but I would like there to be a one click option to install the plugin and activate the theme.

[desrosj]

I had explored adding an "Activate anyway" link to the error screen, but it was turning into a lot of effort.

This was the best way in a short time to address the user flow. @aristath would you be alright including this as is with exploring ways to improve this in 5.8.1?

[aristath]

This was the best way in a short time to address the user flow. @aristath would you be alright including this as is with exploring ways to improve this in 5.8.1?

Sure, makes sense to use this for now until we have a better solution in 5.8.1 👍

[desrosj]

Thanks @aristath! I have opened #53515 to explore improvements.

Also, reclassifying this as an enhancement to better reflect what happened here.

[azaozz]

Thinking [51197] needs a big chunk of inline comments to explain why that code was added to trunk, and that it is temporary (as explained in the above comments). Opening a new ticket as this is a closed enhancement.

[desrosj]

I couldn't find a new ticket for adding more inline documentation that @azaozz mentioned above. But with FSE now slated to be included in full for 5.9, I've created #54366 to remove the changesets for this ticket.