Make style book available to classic themes #8320

carolinan · 2025-02-14T07:45:56Z

This PR is the PHP backport of WordPress/gutenberg#69043.
It is not fully functional without the JavaScript changes.

In this alternative for the stylebook in classic themes, all classic themes have a menu under Appearance called Design.
Design opens the preview of the homepage, and the sidebar has two menu items: Patterns and Styles.
Styles opens the Stylebook. This stylebook is not interactive: not yet. It is a preview of the color palette, blocks etc.
In other words, there is no opt-in for the stylebook, it is available by default.

The PR enables access to the stylebook by:

Registering a new theme support called stylebook. To enable checking for the new theme support in the Site Editor, I needed to make it available in the themes REST API endpoint, which is why I am using https://developer.wordpress.org/reference/functions/register_theme_feature/ with show_in_rest set to true.
Enabling the theme support by default
Updating the menu item under Appearance from Patterns to Design, if the theme support is enabled.

In addition, the PR updates the path to the patterns page, following the recent change to the site editor URLs.

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

Testing Instructions

Activate any classic theme.
Go to Appearance > Design > Styles.
The Stylebook should display correctly.

Add remove_theme_support( 'stylebook' ); to the theme, for example in the themes functions.php file, in the theme setup.
Check that the Appearance menu now has Patterns instead of Design.

(This is the part that needs the JavaScript changes: When you activate the Patterns link, and go back one step, you will see that the style book is still available even though the theme support has been removed.)

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

Make style book available to classic themes by registering a new theme support called "stylebook". The stylebook is enabled by default. Classic themes can opt-out by removing the theme support. When the stylebook theme support is enabled, the "Patterns" menu item under Appearance changes to "Design". When the Design link is activated, the Site Editor shows a preview of the homepage and two menu items: Styles and Patterns.

github-actions · 2025-02-14T07:46:35Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props poena, joemcgill, wildworks.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2025-02-14T07:58:58Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Include the stylebook in the list of theme supports.

joemcgill · 2025-02-23T00:26:32Z

src/wp-admin/menu.php

+	if ( current_theme_supports( 'stylebook' ) ) {
+		$submenu['themes.php'][6] = array( _x( 'Design', 'patterns and stylebook menu item' ), 'edit_theme_options', 'site-editor.php' );
+	} else {
+		$submenu['themes.php'][6] = array( _x( 'Patterns', 'patterns menu item' ), 'edit_theme_options', 'site-editor.php?p=pattern' );
+	}


This approach to modifying the default menu label seems good to me. One nitpick is that I would modify the translator context passed in _x( 'Design', ... ) to say "design menu item" so that the text doesn't need to be updated if additional features are exposed inside the design panel in the future.

joemcgill · 2025-02-23T15:07:41Z

src/wp-includes/theme.php

 * @access private
 */
 function _add_default_theme_supports() {
+	add_theme_support( 'stylebook' );


Would this be the first instance where we are explicitly registering default theme support option in core for all themes? If memory serves, traditionally a feature was only added behind a theme_supports flag in the past if it could only safely be supported as an opt-in feature. I'm happy to go with this approach during beta, but if we intend to ship this feature as a default, we may want to consider a different API rather than theme_supports, unless removing theme_supports will also remove support for the stylebook from block themes as well so the API is applied consistently.

It looks like when the Patterns menu was added, it used the be opt in based on the return value of current_theme_supports( 'block-template-parts' ); but that opt in was removed in https://core.trac.wordpress.org/changeset/58278.

One thing that is missing from this PR is the die handler from https://github.com/WordPress/gutenberg/pull/66851/files#diff-83bd9cbda7dbd9cebb20f6f75ef5a110859f5e81649c43fc6b3823ba30d1098cR119 if the stylebook URL is visited directly from a theme that does not support the stylebook. However, even with that in place it looks like there are issues that need to be addressed with the UI of the editor because even when the menu item is not exposed, the UI is still present once you open the patterns page in the editor.

With theme support:

Screen.Recording.2025-02-22.at.6.02.19.PM.mov

Without theme support registered:

Screen.Recording.2025-02-22.at.6.00.34.PM.mov

Yes you are right: Like I wrote in the description, this is not complete without the JavaScript changes. And those can not be added in this PR, they need to be part of an editor package update.

I share the concern about enabling a theme support only to be able to remove it: It is backwards. The logic is reversed compared to what is normally done.
But since I brought that up in the Gutenberg issue, nobody has been able to share alternative approaches.

I would be very hesitant to introduce a brand new way to opt-out of features.
It is already difficult for extenders to keep track of which method to use to remove or enable features.
So if it is not theme support, in my opinion, it needs to be a different method that already exists.

The die handler change is not part of this PR because it is not compatible with the changes to the path management in #7903.

There was a similar attempt here, but it was closed after review because it was not an ideal solution: WordPress/gutenberg#68959

I don't feel strongly for or against opting out of the block theme style book. The reason why it was not a focus is because of the short amount of time until Beta 1.

carolinan · 2025-02-24T05:10:40Z

There is a separate open Gutenberg Github issue and PR about users of classic themes being able to access the Site Editor if they enter the path to the screen manually:

WordPress/gutenberg#68950
WordPress/gutenberg#69005

…stylebook

joemcgill · 2025-02-24T23:31:15Z

Thanks for the additional context, @carolinan! We've already done an initial sync of editor packages to trunk, but any additional changes that have been made in the last few weeks will likely come over in the next sync. We can double check the remaining UI issues at that point.

Personally, I love this feature for classic themes, and would love to see it included in we can iron out the details so folks can hide it in contexts where it's not desired.

carolinan · 2025-02-25T02:59:10Z

It hasn't been committed to Gutenberg yet.
Two people have suggested so far, that the theme support should also remove the block theme stylebook.
A final decision is needed. Or at least a decision about what to test during the beta.

t-hamano · 2025-02-25T14:20:20Z

What we need to decide are these two things? I might have missed something.

Whether to enable stylebook theme support by default
Whether to disable block theme stylebook when the stylebook theme support is disabled

joemcgill · 2025-02-25T19:25:24Z

For an initial commit of the underlying theme_support changes that are required (i.e., this PR), I'm happy for this to be enabled by default during the beta period. I would defer to @carolinan and the other editor leads about whether being able to opt-out by removing theme support should also remove theme support for block themes, but my gut says that the API should work consistently regardless of theme type.

carolinan added 3 commits February 14, 2025 09:16

Update WP_Test_REST_Themes_Controller

392463b

Include the stylebook in the list of theme supports.

Add since tags

684421c

Merge branch 'trunk' into add/62509-classic-stylebook

a9e5f86

joemcgill reviewed Feb 23, 2025

View reviewed changes

carolinan mentioned this pull request Feb 24, 2025

Make it possible to opt-out of the classic theme Stylebook WordPress/gutenberg#69043

Open

carolinan added 2 commits February 24, 2025 06:59

Merge remote-tracking branch 'upstream/trunk' into add/62509-classic-…

678cab4

…stylebook

Update the translation context for the Design menu item

17dd9b5

This was referenced Feb 25, 2025

Feedback on adoption approach for exposing editable UI for the Style Book for Classic themes WordPress/gutenberg#68036

Open

Modify appearance submenu when stylebook is supported #8429

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make style book available to classic themes #8320

Make style book available to classic themes #8320

carolinan commented Feb 14, 2025

github-actions bot commented Feb 14, 2025 •

edited

Loading

github-actions bot commented Feb 14, 2025

joemcgill Feb 23, 2025

joemcgill Feb 23, 2025

carolinan Feb 23, 2025

carolinan Feb 23, 2025 •

edited

Loading

carolinan Feb 23, 2025

carolinan commented Feb 24, 2025

joemcgill commented Feb 24, 2025

carolinan commented Feb 25, 2025

t-hamano commented Feb 25, 2025

joemcgill commented Feb 25, 2025

Make style book available to classic themes #8320

Are you sure you want to change the base?

Make style book available to classic themes #8320

Conversation

carolinan commented Feb 14, 2025

Testing Instructions

github-actions bot commented Feb 14, 2025 • edited Loading

github-actions bot commented Feb 14, 2025

Test using WordPress Playground

Some things to be aware of

joemcgill Feb 23, 2025

Choose a reason for hiding this comment

joemcgill Feb 23, 2025

Choose a reason for hiding this comment

carolinan Feb 23, 2025

Choose a reason for hiding this comment

carolinan Feb 23, 2025 • edited Loading

Choose a reason for hiding this comment

carolinan Feb 23, 2025

Choose a reason for hiding this comment

carolinan commented Feb 24, 2025

joemcgill commented Feb 24, 2025

carolinan commented Feb 25, 2025

t-hamano commented Feb 25, 2025

joemcgill commented Feb 25, 2025

github-actions bot commented Feb 14, 2025 •

edited

Loading

carolinan Feb 23, 2025 •

edited

Loading