Open celloexpressions opened 3 years ago
Great write-up. Thank you for the time it took to compile all of that.
I believe you're right: The customizer (in some form) is here to stay. At least for a good long while. The question to answer is what to do about that.
I think that it will be important to FIRST ensure that block-based themes are use-able in the existing customizer workflow, without a dependency on the FSE. I think this could allow the growth of either Approach 1 or Approach 3 noted above. I'm a strong believe that we SHOULD NOT COUPLE how we BUILD themes (Global Styles/HTML-block-based templates) with how a user MANAGES those themes (Customizer/FSE). Themes should have control of how their customization options are presented to the user.
Bouncing a user back-and-forth (change this here, but if you want to change that go there) definitely seems like a poor experience for a user though and I hope that's not the road we go down. I like the idea of bring enough of the FSE into the Customizer (a Global Styles panel, template editing, etc) to empower a user to manage their site exclusively there without complicated overhead in theme authoring.
Yet the inverse to that also means that many of the features currently exclusive to the customizer likewise need attention in the FSE (or at least migration OUT of the customizer). So that a user can effectively manage a site with the FSE INSTEAD of the customizer.
If a theme needs both interfaces then I believe we have failed.
If a FSE theme can't use either interfaces FOR BASIC MANAGEMENT I also believe we have failed.
Thanks for the thorough report.
This enumeration can serve as a starting point for tracking some features we might be missing in the new block-based customisation flows. Some of them are known to be missing and are planned (e.g. navigation mode), some others are AFAIK being deferred while other pieces of the puzzle fall into place (e.g. CSS, Site Icon), and some are great things to draw attention to (e.g. how do we best handle customisation drafting and revisions¹, and how does this tie with the next big phases² — collaboration and multilingual — of the Block Editor?)
What is clear to me is that block themes and FSE represent a stark enough departure from traditional themes to warrant a rethinking of how we interact and relate with the canvas of a website, now that it is reified by blocks. This is not a new idea, but is worth stressing in any discussion about feature parity.
With that in mind, I'm not convinced that Gutenberg should turn to the Customiser API or infrastructure for its own goals. Its architecture and data models are fundamentally different, and a lot of Gutenberg's infrastructure built so far for phases 1 and 2 is well suited to power FSE.
For me, the Customiser is a solid and powerful system that was developed to accommodate the variety and complexity of traditional PHP-based themes. Just like themes themselves, it's not going away anytime soon. But, just as we had to move away from traditional themes to reimagine content and customisation, so too we have to move away from the system that was shaped by and for that legacy.
As for action items in this issue, I think it will be very useful for us all to revisit it in a few weeks, then a few months, and open up a series of focused issues of things to add to FSE.
¹: Having revisions for all the chunks of content that make FSE up, including Global Styles, is important and definitely in the plans. ²: WordPress Tavern: State of the Word 2019 Recap: All Roads Lead to the Block Editor, § The Next Steps for the Block Editor
As written, this issue treats the "site editor" as a standalone interface, separate from the post editor and the customizer. Some site editing features will (likely) be available as an extension of the post editor in WordPress 5.8. However, we're not quite to the point of adding a third "place" to edit a site yet as of 5.8.
The bigger backwards compatibility problem will happen when "full" block-based themes are fully supported. And that is the definition of "MVP" that this issue is framed with. If the current strategy to hide the customizer for those themes is to be maintained, then full feature parity is required. Or the customizer can be shown for all themes and we can deal with maintaining two different interfaces (approach 1).
Decisions about types of themes and how they're edited probably need to be finalized first. Then, we can dig further into the possible approaches outlined in this issue and decide how to ensure feature parity and smooth transitions for users. Ideally blocks will enable using a single interface to edit any aspect of a site. But in the process of getting there we're leaving millions of sites using traditional themes in a place where there are two or even three different places where you can edit different parts of a site.
That's where expanding on widgets in the customizer with Approach 2 could be a good fit for hybrid theme models even if that isn't the final direction for "new" themes. And a lot of this comes down to the idea of hiding the customizer for some themes. If that happens, then we need to do more work for feature parity but also for API parity for plugins, and approach 3 comes into play.
In terms of Gutenberg not turning "to the Customiser API or infrastructure for its own goals", we need to look way beyond what most people think the customizer is. There are tons of missed opportunities coming out of the project approach to reinventing the wheel. Yes, it's great to start with a clean slate and leave years of technical debt behind. But more technical debt is actually being created in the process. And a lot of it cascades to plugin developers, theme authors, and site owners as a result of core decisions.
For example, the customizer already has a robust API to track revisions to any aspect of a site. But a full UI hasn't been built out yet. Building another full revisions system seems like a wasted effort, when the existing core API (and corresponding post type) can be integrated with a new design in the block editor framework. Another example is that the customizer has always worked with iframes to ensure high-fidelity previews, which the block editor is turning to later in its development.
This is a separate discussion from the specific compatibility items that this issue focuses on. However, I would encourage the team to take a deep look at existing core functionality before going too deep into any new features to leverage existing work when we can.
Thanks for opening this issue Nick. You echo a lot of my thoughts about the mis-steps of this project.
From all the excitement about "building the future!!!" there is a risk of throwing the baby out with the bathwater. The goal of this project is not to "build the future" or "re-imagine" but to basically replace legacy content formats (unstructured post content, shortcodes, widgets, PHP theme templates) with block-based formats, and to provide a well-designed UI for those blocks. It may sound less romantic, but romantic often means vague and ill-defined.
Many components of the customiser, as you explained, are not necessarily tied to legacy content formats, and could work equally well with block-based content. There is no reason those components need to be thrown out, much less re-built in ways that are likely to be inferior to the original. If the project starts throwing out and re-building inferior versions of features that are not "the problem" and are agnostic of content format, then the project is losing sight of its purpose.
This mistake is already being made in other areas. I have recently been working on a patch at #31971 that re-builds a piece of infrastructure that was added to the plugin in the past year. The current version "re-imagines" taxonomies and slugs, i.e. misuses them for purposes they were never designed for, adding to complexity and taking away flexibility. My version uses theme mods, which were designed for exactly this purpose and remove the complexity and inflexibility, but have strangely been overlooked by the team for the past year. I hope it's not because they associate theme mods with the "old" way of building themes, because theme mods are agnostic of content format and this project is about upgrading content formats.
The same is true for many components of the customiser infrastructure. The aim should be to preserve whatever underlying infrastructure is capable of supporting blocks, re-building only where the old infrastructure is lacking, while keeping the user experience consolidated in one place.
@carlomanf it's good to reiterate goals from time to time so we do not lose sight of it but I think that formulation above falls a bit short. The goal is to have a customization experience based around direct manipulation and expressive design tools. Using blocks and consolidating formats to achieve it is more of a strategy than a goal, given blocks were conceptualized with direct manipulation from the get go. The customizer was instead conceptualized with indirect manipulation and a refreshing preview. While there's always a lot to reuse and not reinvent unnecessarily, these two models are at odds. Blocks on their own also don't do anything, they need a block editor to perform. If it was about throwing things away we might not even be using themes, or the theme hierarchy! We should be using and reflecting on the right infrastructure for each piece, given the current and past trajectory of WordPress. There should be no reluctance to using theme_mods if it solves a problem well. Theme switching is riddled with intricacies and poor usability that we are set to attempt improving, given a lot more options are open now for mixing theme templates and patterns that we should think deeply about.
I believe that the Customizer needs to stay in some form or another. Themes aren't the only thing that put settings in the Customizer. Plugins also put their display output settings in the Customizer screen. When testing Full Site Editing, I noticed that there is no longer a way to get to those settings.
I'll jump in here as well, as I noted this wasn't brought up in the go/no-go discussion, nor in any of the WordPress 5-9 Must-Haves, but is definitely important to address.
Currently a lot of plugins will (should?) have put settings relating to the visual presentation of their content into the Customizer when it's global settings that do not boil down to individual blocks, this is where I feel the big shortcomings currently lie.
The Site Editor addresses styles, and this feels natural in its context, but "Settings", for lack of a more grand scope, do not fit into the current scope here. Going to the site editor lets you edit individual templates, it has global styles (emphasis here on it being styles, while a plugin, or theme, might have a global site option that defines how to trigger a style).
In a blanket removal of the Customizer for any FSE-enabled theme, we are likely to hamstring a lot of plugins, or create a bit of a nightmare for them, I know this has been brought up before in discussions, without a resolution, but with the recent release of a WPTavern article covering the lack of a Customizer as well, where one of the proposed solutions is for plugins to add their own Customizer links, we might end up with multiple references to the Customizer, instead of a canonical means of reaching it, further confusing users in the process.
And just to have it covered; Yes, a plugin could re-introduce the Customizer link, but we should not be creating a dependency on a plugin to be able to find the canonical location for settings. I've focused a lot on plugins in m,y response, but the WordPress handbook does, to this date, state that the Customzier is the canonical location for any theme options, some devs may, rightfully so, presume that means that "yes styles go into theme.json
for their full site edited theme, but their options go in the Customzier". So feature parity before we "kill" the Customizer by not making it's entry-point be provided by core is definitely an important aspect that needs to be thoroughly discussed.
Edit: Added missed reference to core plugin to re-introduce the Customzier link.
Edit: This actionable issue has been split out into its own ticket in #35874
Just a little nitpick (Nickpick?)
Themes can be installed, customized and staged (as a draft, for review by others, or scheduled for future publication) within a customizer session.
I can't find where you can draft a theme change. I've often wanted to, but the Customizer only shows the Save Draft when making changes to the active theme, not a Live Preview theme.
From the WPTavern article:
WordPress should automatically detect filters or actions on customizer-related hooks. This should trigger a “customize supports” flag and maintain the admin menu and toolbar links to the customizer screen. This would give developers some time to catch up without confusing users in the process. There might be a few false flags or missed integrations, but it should be able to effectively catch the majority of use cases.
This sounds reasonable to me. I'd like to see a PR or patch which explores how feasible it is.
The customizer is a framework for live previewing any change to a site. This framework contextually shows and hides features based on criteria such as the theme-supports and active_callback APIs. Block themes are fully compatible with the customizer framework as-is: they do not support additional customizer features and those features are automatically hidden.
Until there is full compatibility for core customizer features in a new (block-oriented) interface, the customizer cannot be hidden. Regardless of whether or not it shows theme-specific features. In my initial re-testing, none of the eight higher-priority customize-only features originally identified in this audit have equivalents in the site editor as of Gutenberg 11.7. Even if work is progressing on some of them, it will take time to achieve feature parity. It took years for the customizer to approach feature parity with the wp-admin Appearance section, and the wp-admin interfaces are still shown for some features that never achieved full parity.
Beyond the immediate lack of core feature compatibility, conditionally showing the customize framework based on registered plugin usage creates a disorienting and confusing user experience. This cascades into difficult and inconsistent support workflows across themes, plugins, and site implementers. I have long advocated for consolidating WordPress interfaces rather than maintaining multiple ways to make a given change to a site. But until there is feature parity and API continuity in a replacement, hiding the customizer breaks WordPress' commitment to backwards compatibility, compromising user and extender trust.
The purpose of this issue is to identify a long-term solution for compatibility. A majority of sites will not switch to a block-based theme for many years, if ever. As the block-based site editor evolves to provide full feature parity, it would be great to see a gradual transition to move customizer usage to this interface (similar to post-editing metaboxes coming over from the classic editor) (Approach 3) or to bring site editing features to the customizer (similar to existing work with widgets) (Approach 2).
Until those ideas are developed and implemented, Approach 1 is the only reasonable option to avoid breakage. For the immediate future (and WordPress 5.9), the customizer should not be hidden based on a theme conditional. The new site editing features can be added as an iterative improvement without taking other core features away.
I can't find where you can draft a theme change. I've often wanted to, but the Customizer only shows the Save Draft when making changes to the active theme, not a Live Preview theme.
@joyously This currently requires some workarounds, see this pending core ticket for potential improvements.
And features at the periphery of the site editor scope, from theme switching to additional CSS, are already implemented.
Am I missing something - how is additional CSS implemented?
Ah - I get it - Additional CSS is already implemented - in the customizer - which is hidden for FSE.
So when supporting users with minor CSS tweaks - what is the expected behaviour - tell them there is a feature but it is hidden but use this 'secret' link and it will work?
The full-site editor seeks to replace the customizer in the long term. The customizer is currently hidden whenever a block-based theme is active. However, there are functionality and compatibility gaps in this experience. Most notably, core customize features and plugin settings in the customizer are not inherently replaced by the site editor like theme settings are.
This issue documents the current incompatibilities (backwards compatibility issues). It also explores high-level options to close the compatibility gaps and ensure that users can safely switch to an FSE theme in a production context. Given the context and severity of the breakage, this needs to be addressed before the site editor can ship with WordPress core.
General Approach
The current approach in the plugin (#26594) hides the customizer when an FSE theme is active. But it does not adequately address backwards compatibility for non-theme-related customizer features within the site editor. This is not an acceptable experience in terms of the project’s commitment to backwards compatibility. There are three general strategies that can ensure compatibility in the customizer to site editor transition:
Approach 1 (multiple interfaces) is the most cumbersome for users, theme and plugin authors, and core developers. However, it can be enabled quickly (primarily by reverting #26594). This would be a temporary solution to ship an MVP. It should only be considered if the resulting experience is deemed acceptable (enough, for now) relative to the potential time delay to release an MVP that could be required to pursue the other options.
Approach 2 (unified interface) may sound technically unrealistic to those familiar more with Gutenberg than WordPress core. However, the customizer has envisioned an evolution to enable “full site editing” in its roadmap for some time. The customizer is an API and a framework more than it is the user interface that currently exists. It is very possible to frame the site editor (and also the post editor) as an extension of the customizer rather than a completely separate interface. This approach could make significant changes to the customizer interface and its existing features. Under the hood, the existing customize API would continue working and the site editor could leverage the existing robust frameworks for live preview and site-wide change management (changesets). For users there would be a much-more-seamless transition between FSE and non-FSE themes with site editor features replacing theme settings in a similar interface context as appropriate. The site editor as currently envisioned fits better as an extension of the customizer than as a replacement for it.
Approach 3 (separate interfaces per theme) would create similar usability and long-term maintenance challenges to option 1 for all parties. However, it may require less implementation effort from the Gutenberg team. This would build on the current plan to keep the customizer for existing themes and replace it with the site editor for FSE themes. It would also bridge the functionality and compatibly gaps that currently exist. The items that need to be addressed to make this approach workable are documented below under “Customizer-only Features”.
If the customizer is to be maintained for existing themes, separately from the site editor, it will likely need to remain permanently. Unlike the plan to eventually drop support for the classic editor, dropping support for the customizer would require all sites to eventually change themes, which is not a practical reality for WordPress to mandate. The theme-switching experience could become particularly painful if option 3 is the path forward, noting the likely need to switch back and forth between traditional and FSE themes and the theme-switching flow currently built into the customize experience.
Specific Feature Compatibility Status
This section audits the feature and compatibility differences between the customizer and the site editor as of Gutenberg version 10.3.1. The cross-compatible features are listed for progress tracking and to note differences that might propagate to compatibility issues. The incompatible features need to be addressed prior to releasing FSE in core, unless general approach 1 (dual interfaces) is selected.
Cross-Compatible Features
The following features exist in both contexts. Implementation differences are noted below. Care should be taken to ensure cross-compatibility when switching theme types and if approach 1 (multiple interfaces) is selected:
Site-Editor-Only Features
These features exist in the site editor but not in the customizer. These would need to be ported to the site editor context to work within the customize API context to pursue approach 2 (unified interface).
While the features that it implements are complex, the site editor focuses on a few distinct functionalities. Each item could be reasonably treated as an extension of the customizer via custom panels. They are additive enhancements to current ways that users can customize themes.
The site editor would benefit from the infrastructure that the customizer offers. High-fidelity live previews are the customizer’s central focus. The customize changesets API provides drafts and scheduling for site-wide changes. And features at the periphery of the site editor scope, from theme switching to additional CSS, are already implemented.
Approach 2 (unified interface) could extend the customizer with a new panel for template editing when a compatible theme is active (or previewed). When opened, the panel could “take over” the customizer preview with the editable block-based preview. Global styles could be integrated into this takeover or serve as a separate customize panel to emphasize the separation of style controls from inline editing in the preview. In general, the site editor would remain intact as currently designed, but with the added context and capabilities of the customizer. The relevant customizer features and API would continue to operate alongside the site editor for items that are not superseded by full site editing. And the superseded items would be hidden as needed. This project could optionally redesign the rest of the customizer to integrate more fully with the site editor design.
Customizer-Only Features
These features exist in the customizer but not in the site editor (as of Gutenberg version 10.3.1). Backwards compatibility needs to be included in the site editor if approach 3 (separate interfaces per theme) is selected (except where noted for legacy themes). The sub-bullet points describe broken workflows/use cases and potential mitigation.
Higher Priority
Lower Priority (noted for completeness)
These items may prompt adjustments to the site editor but probably won’t need to be ported for compatibility.
Potential Integration with the Site Editor
Many of the features listed above could be integrated with the site editor. However, some of them would take significant time and effort, considering the ten-year history of customizer development in core. All of the high priority features should likely continue to function with block-based themes. A more detailed feasibility study should confirm which features should be integrated with the site editor, and how, if Approach 3 (separate interfaces per theme) is selected.
Conclusion & Next Steps
The site editor integrates many specific features that the customizer offers. But it does not have the same overall scope and goals in its current implementation. There are currently numerous missing customizer features in the site editor. These can be seen as regressions or general breakage of varying severity for users and plugin authors, especially if the customizer is hidden when block-based themes are active.
The next step is to decide on a general approach to resolving the incompatibility before the site editor is released in WordPress core. The lists above can serve as a reference for making an informed decision, and as checklists to address specific items. If approach 1 is selected for now, then this issue can guide a longer-term project to improve compatibility in the future.
If further analysis concludes that any existing customizer features or APIs should be formally abandoned or deprecated, then those decisions should be adequately communicated to plugin authors and the broader community. Plugin authors in particular need sufficient time to react to such changes before they are introduced in WordPress Core.