Site Editor: MVP Customizer Compatibility/Integration #30496
Comments
annezazu
added
[Feature] Full Site Editing
[Type] Discussion
|
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. |
|
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 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?)
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:
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.
@joyously This currently requires some workarounds, see this pending core ticket for potential improvements. |
|
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? |
annezazu
added
[Feature] Site Editor
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:
a. Customizer access is directly available (including contextual preview) from the wp admin bar on the front end.
b. Site/template editing is accessed after first editing a post and is somewhat hidden. Consider improving this workflow separately from the standalone site editor.
a. Customizer provides smaller-screen previews in one click. Site editor requires two clicks. Consider simplifying the site (and post) editor designs to match the customizer for quicker access.
b. Customizer includes a button that hides all customization UI to show a full-screen preview. Site editor requires closing several UI panels separately to get a similar result. Consider incorporating a full screen/collapse toggle similar to the customizer.
a. Customizer shows edit icons in the preview that link to customization UI. Site editor includes various icons and styles to indicate editability, although many are only accessible with a mouse.
a. Customizer will be limited to editing blocks within theme-defined widget areas. Site editor is fully block-based.
b. Widgets need to be hidden in the customizer when a block-based theme is used, or maintain their editability as a template part in the customizer.
a. Both interfaces support menus. However, the menu editors are not cross-compatible. Updating the customizer menus panel to match the new navigation block would improve compatibility when switching between the interfaces.
b. Menus panel should be hidden in the customizer if block-based theme menus are not editable in the customizer.
c. The navigation block includes significant regressions relative to the features currently available for menus in the customizer. These need to be audited in a separate issue.
a. The cover block can generally replicate this theme-support feature.
b. There is not complete feature parity. For example, there isn’t an obvious way to set a fallback image for a header video in the site editor. The site editor gives less control over cropping/image alignment. The customizer includes a library of previously used headers that facilitates workflows like seasonally rotating headers.
a. Unlike site icons, this is a theme-specific feature in the customizer. The term “custom” (not “site”) reinforces this distinction.
b. Theme authors implemented logos with ad-hoc image options before this core feature was introduced. Image blocks may be used more than the site logo block in the site editor. This topic could use a dedicated conversation to explore implications either way.
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).
a. Widget areas are the only similar feature for non-FSE themes.
b. This only works for new block-based themes as currently implemented.
a. Some existing themes implement similar settings as theme options.
b. This can only work for new block-based themes as envisioned.
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
a. This functionality is critical to understanding how edits apply to different views on a site. While FSE allows navigation by template, there is a disconnect with understanding and previewing the actual content that each template will show.
b. Site navigation can be particularly helpful when editing menus to confirm menu links work as intended.
c. Site editor: Add Browse Mode #23328 and Site Editor - 'Preview Site' feature. #29398 discuss this topic. The direction there may lead to a separate preview that is not live (like the post editor) instead of the live preview that the customizer offers.
d. The customizer also provides direct navigation back to the frontend, contextual to the previewed page, when closing. Consider including similar navigation in the site editor.
a. This is important for review workflows and staging changes. Excluding from FSE is a significant usability regression.
a. The customize API is intended for use in both themes and plugins. Any theme options are expected to be superseded by the site editor and global styles. Plugin options generally need to continue working regardless of the theme’s status as traditional or block-based.
b. Plugin authors would need significant time to migrate their options from the customizer to the site editor or wp-admin if the customize API were to be deprecated (even for certain types of themes).
c. Plugin options could be incorporated into the site editor similarly to the way that plugin meta boxes are incorporated into the block post editor for backwards compatibility. This would likely involve running the customize_register action and displaying plugin-registered panels, sections, and controls, while maintain the ability to save (and hopefully also preview) settings. Plugin-specified sections and panels would likely use a different PHP object and UI output in the site editor than in the customizer. Custom control types (including the core media and color customize controls) should continue working. Some degree of breakage could be allowable for custom section and panel types. The customize JS API would need to continue working for controls but could potentially be eliminated for the “preview pane” in the site editor context.
d. Integrating aspects of the customize API into the site editor could also ease the transition for core features built on the API (continued in this list below).
a. Themes are the first hierarchy in site customization. The customizer includes an integrated theme browser, installer, and switcher to promote themes as a fundamental part of editing the site design.
b. The customizer theme installer features a one-click “install and preview” button. This enables users to live preview a theme on their site with their content and immediately start customizing (or selecting another theme), rather than first previewing the theme with dummy content.
c. Themes can be installed, customized and staged (as a draft, for review by others, or scheduled for future publication) within a customizer session.
d. The site editor currently makes no reference to themes or the ability to switch themes.
e. The customize/live preview flow is also integrated with the themes screen in wp-admin.
a. The site editor allows the index (blog/posts) and page templates to be customized. But there isn’t a clear way to control which template applies to the front page or what pages are used for front and blog.
b. The customizer shows these options and the corresponding live preview so that users understand the consequence of changing the setting. Navigating the preview through menus reinforces user confidence in their selections for these options.
c. The customizer also includes the ability to add a new page inline and assign it to the front page or blog page. This is especially helpful when first setting up a site, and considering that no further action is required to set up/edit the blog page placeholder.
a. The customizer allows users to create new placeholder pages (and posts) as they build navigation menus. This is a powerful workflow when setting up a site or when staging a redesign. Further editor/block integration could allow users to add content to these pages within the staging environment.
b. The site editor and navigation block do not appear to have similar capabilities.
a. Additional CSS gives users greater control over their site’s appearance in exchange for a deeper technical dive. It serves as a much more forgiving introduction to code editing than the theme (code) editor in wp-admin, aided significantly by instant live preview.
b. The site editor and global styles should reduce the need for additional CSS in common scenarios. But they cannot replace the need for a greater level of customization at a granular site-specific level.
c. Additional CSS is a useful tool for support and for plugin customization. Plugin authors can offer libraries of CSS snippets to make changes that are requested occasionally but do not warrant user-facing options (see the WordPress Philosophy, particularly “decisions, not options”). Support technicians can assist with writing CSS to address site-specific bugs and help users apply, preview, and save the fix to their site.
a. See Site Editor: not possible to change site icon #29126 for preliminary discussion.
b. Research the discussions that concluded in showing site icon option in the customizer and not in Settings -> General when the feature was introduced in 2015 before considering adding the setting there as a fallback.
Lower Priority (noted for completeness)
These items may prompt adjustments to the site editor but probably won’t need to be ported for compatibility.
a. Hiding the site tagline is a common support request. The tagline is often hidden before a user deletes or changes its text. But the title and tagline are used for the HTML title attribute for the site even if they aren’t shown on the front end. The site editor makes it easier to accidentally remove a tagline from the frontend, while keeping an unintended “just another WordPress site” shown to users, and making it harder to find how to remove it.
a. It may be possible to set a background image, but without the depth of control that the customizer offers (when themes add support).
b. Replicating a theme like Twenty Fifteen in the site editor would be a good exercise to evaluate how well this concept can be achieved with the current block options.
a. When installing a FSE theme from the customizer theme browser, the live preview in the customizer is automatically opened. There is no indication that the theme is not intended to be customized here, and many features do not work as expected. There is no indication that the customizer will “disappear” once you exit, making it unclear how to “go back.”
b. The current workflow allows for experimentation and previewing without breaking the live site. Users could dial in theme settings before committing to a change. There is no longer a clear way to stage a new FSE theme with live preview before activating it live on the site.
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.
The text was updated successfully, but these errors were encountered: