[Discussion] Hybrid themes: Templating hierarchies

[aristath]

With the current implementation of FSE, there is a big disconnect and schism between "classic" and FSE themes. However, with a few changes, we can be more versatile and fluid, ultimately making the transition to FSE easier for both themers & end-users.
For starters, we should have no such concept as an "FSE theme". An FSE theme is nothing but a theme that only uses FSE templates.

• Themes should not have to opt-in to FSE.
• FSE should not be on a per-theme basis, but on a per-template basis. A “classic” theme can just have the single-post template as a block-template, while everything else is on a PHP structure.
• Users should be able to create an FSE template on any theme, without affecting the overall theme structure. So if a user creates a template called page-67, then the theme should work like before - with the exception of page 67 where the user-created template will take precedence.

The templating system can work like this:

• If there is a user-edited FSE template, use that.
• If there is no user-edited FSE template, but there is a block template, use the block template (currently the block-templates/*.html files)
• If there is no user-edited FSE template and no block-template file in the theme, fallback to the .php file.

With the above priorities and checks in place, we could accomplish hybrid themes.
It will not be classic OR FSE; it will be a mix that can support both PHP templates & block templates, both for page templates and template-parts. The result will be an easier migration path and more granular control.

Themers could start migrating their template-parts one at a time, and they can be picked up by the get_template_part() function in the beginning. Then they can move on to migrating the structure of full templates one at a time, without the need to do everything in a single time-consuming and over-complex migration.
The current implementation of requiring an explicit "FSE theme" works fine while in the experimental/development phase, so it's an intermediate step, a stage in the path towards FSE in Core. But it should not be the end-goal.
In order to get where we want to go with the templating system, we need to make a few changes and take a lot some things into account.

Template priorities

This one seems like a non-brainer. User-edited (or user-created) templates should be loaded first with a fallback to theme-provided block templates and ultimately a fallback to a php template if one exists.

Big-picture questions:

• What happens when the user has saved a template and then we switch themes?
• The site editor should not always be available in classic themes, but we need to find a way to make it available… Maybe a switch in the post-editor itself, making it possible to switch between editors and create a template for the post/page we were previously editing?
• How is the user going to create their 1st template in a “classic” theme?
• The “site-editor” admin menu should only show by default if the theme has a block-templates folder or if there are user-created block-templates.
• We should allow loading a PHP template-part in the template-part block. Needs some UI to make it clear that these are not editable but are use-as-is, or replace with custom

In the template overview, we could list all templates, both classic templates, FSE templates defined in the theme and User defined templates. When someone clicks a classic template, this opens the customizer. It's a much nicer gateway to the customizer anyway. If the classic templates are listed as well, we could create an option to create a custom template for them.

Related: #24313

Proof of concept PR: #29298

[youknowriad]

What happens when the user has saved a template and then we switch themes?

Right now, FSE theme switching don't retain edited templates either which means this might be a question for another time.

[youknowriad]

Another question:

• What blocks are available in the post editor to which themes. Right now, when you have an FSE theme, a ton of new blocks become available.

[youknowriad]

Some other questions:

• Right now, we enable per block stylesheet for FSE themes, what would it mean here?
• Right now, we allow persisted global styles for FSE themes, what would it mean here?
• What about custom page templates? Should we "merge" custom php templates and custom html templates? Is it doable?
• To simplify the WP-Admin UI, we hide the customizer and the widgets screen for FSE themes? When should this happen?
• We were considering automatically iframing the post editor for FSE themes.

Basically, there's a number of situations where we rely on the fact that FSE themes are a breaking change which allow us to introduce better APIs, better flows without the worry to have to support existing themes. That's a good thing, and mixed approaches will make this harder. We need to find a way to do define: a "full" FSE theme IMO.

[aristath]

What blocks are available in the post editor to which themes. Right now, when you have an FSE theme, a ton of new blocks become available.

This will need to change and not be on a per-theme basis, but on a per-template basis. So if a post/page is based on a PHP template then the FSE blocks will be hidden, but if the post/page has a block-template associated with it then the FSE blocks should be available.

Right now, we enable per block stylesheet for FSE themes, what would it mean here?

Themes can opt-in to the per-block stylesheet regardless of whether they are FSE or not. If they don't opt-in, then per-block styles would be used for FSE templates, and the legacy styles for legacy templates.

Right now, we allow persisted global styles for FSE themes, what would it mean here?

This would probably also be on a per-template basis.

What about custom page templates? Should we "merge" custom php templates and custom html templates? Is it doable?

I made a small PR on #29026 to demonstrate how that can be done... It's certainly doable!

To simplify the WP-Admin UI, we hide the customizer and the widgets screen for FSE themes? When should this happen?

One thing I was thinking about was to only hide these if there are no PHP templates in the theme. So if ALL templates are block-templates, then it's an 100% FSE theme and these can therefore be hidden. If however there are PHP templates that are used (so a page.php file but no block-templates/page.html, and no page user-created block template) then the customizer & widget screens will need to be shown.

We were considering automatically iframing the post editor for FSE themes.

We could iframe the post-editor regardless of whether it's an FSE theme or not.

---

I agree that are are a lot of things to consider and discuss - mostly the UI/UX aspect. But these things could go a long way towards avoiding a schism between classic & FSE themes...

[youknowriad]

So if a post/page is based on a PHP template then the FSE blocks will be hidden, but if the post/page has a block-template associated with it then the FSE blocks should be available.

This doesn't really make sense to me. Why should I be able to use "Site title" in the post content of a page depending on its template?

Right now, we allow persisted global styles for FSE themes, what would it mean here?

This also doesn't seem good per template since you expect your entire website to adapt IMO

#29026

This is about the template loader, I was talking more about the editor side of things (assigning custom templates), can I assign a php template or html template interchangeably? Can I have both php and html with the same name for custom templates?

We could iframe the post-editor regardless of whether it's an FSE theme or not.

No, we can't unfortunately, it creates too much breaking changes for block plugins.

[aristath]

This doesn't really make sense to me. Why should I be able to use "Site title" in the post content of a page depending on its template?

Then perhaps FSE blocks should only be available in the site-editor and not the post-editor? FSE blocks can be shown in the post-editor if the theme does not contain any php templates, in which case it's an 100% FSE theme. How does that sound?

This also doesn't seem good per template since you expect your entire website to adapt IMO

I agree, we'll need to find some other solution. We'll keep thinking, I'm sure we'll come up with something!

This is about the template loader, I was talking more about the editor side of things (assigning custom templates), can I assign a php template or html template interchangeably?

Yeah, I honestly have no idea how that could be handled! I suppose we could show both PHP & HTML templates 🤔

Can I have both php and html with the same name for custom templates?

I would say no... The template name would be the identifier so user-created would override theme-provided html templates which in turn would override php theme-provided templates. Only 1 of them would be visible.

[youknowriad]

Then perhaps FSE blocks should only be available in the site-editor and not the post-editor? FSE blocks can be shown in the post-editor if the theme does not contain any php templates, in which case it's an 100% FSE theme. How does that sound?

Yes, I'm still not sure yet, it can also depend on the "parent/ancestor" blocks for some blocks. Some of these blocks are also not that different from existing widgets blocks available in the post editor. So I wonder if the most reasonable approach is just to make these available everywhere by default (when we consider them stable enough)

[skorasaurus]

Thanks for picking up this discussion again; @tomjn had proposed a template hierarchy in #24803 ; #24834 also has similar discussion

[MaggieCabrera]

This discussion is mainly about templating but I think it's fair to at least mention that GS should not be tied to FSE for themes to opt in to them. A theme may not have (or want to have) FSE templates at all but may want to include Global Styles using theme.json to improve it, thus making it hybrid in some way too.

[lukecarbis]

Separating Global Styles from the Site Editor makes a lot of sense to me too.

To me, the biggest point of friction for incorporating "classic" themes into the Site Editor is not having a "starting point" – the first template would need to be designed from scratch.

It also seems likely that themes could break entirely. For example, suppose the theme author implements the site's title with a <h2> tag, maybe with an unusual class like website-title or something, and it's inside a <div>.

Their CSS selector might look like .top h2.website-title. There's no simple way of getting these title styles to apply to a Site Title block. Combine this with a bunch of different areas, the menu, the tagline, the sidebar, etc. etc… I just don't see how this could work at all.

[bph]

Here is a use-case that has been ruminating around my head since I first talked to Enrique about FSE in 2019 (!)

I have a site with a podcast = think Custom Post Type. The archive page for the episodes that comes from the plugin by default is basic and virtually unusable. I use the 2019 default theme.

I would want to create a new archive page with the Site Editor, that inherits all the styles, header, menu, content areas, widgets and footer from the main theme.

All I would want to change is: A page title, some paragraph/image on the top and change how the loop is displayed, from a list to a 3 column grid.

Plenty of plugins provide additional CPTs with minimal design, but I (a site owner) shouldn't need a theme developer to change the display of the CPT posts. I don't know if it's feasible, to make this available for conventional themes, but it would be a great selling point for FSE If using a new feature in WordPress does not mean I have to rip out again my theme that I just got with my blocks, it would mean the world to me. haha.

It would shorten the adoption cycle by two years or so...

[Sandstromer]

Would it be possible for a theme author to create a theme that looks and behaves like a FSE theme on the frontend, but with the Site Editing disabled?

What I mean is taking the essence of FSE templates and template parts, but rendering them in classic style php templates.
For example echoing blocks with do_blocks() in a classic php template, and leaving out the equivalent FSE html template.

If this will be possible, I could potentially see some theme authors offering a premium version that "unlocks" the Site Editor with the html templates only included in the premium version.

Or have I got it completely wrong? Will classic php templates be editable in the Site Editor?

Personally I would not like to see the theme repository hosting such "crippleware" themes, if that does become possible.

[aristath]

Plenty of plugins provide additional CPTs with minimal design, but I (a site owner) shouldn't need a theme developer to change the display of the CPT posts. I don't know if it's feasible, to make this available for conventional themes, but it would be a great selling point for FSE If using a new feature in WordPress does not mean I have to rip out again my theme that I just got with my blocks, it would mean the world to me. haha.

With a hybrid model this would be possible. If the site-owner has access to the site-editor in "classic" themes, then they would be able to create a template, use archive-myPostType as the template-title, and then do whatever they want with it. Everything on the site would work like before. with the exception of archives for the myPostType post-type which would work via the FSE template.
That's why in my OP above I mentioned that FSE should be on a per-template basis and not a per-theme basis 😉

Would it be possible for a theme author to create a theme that looks and behaves like a FSE theme on the frontend, but with the Site Editing disabled?

What I mean is taking the essence of FSE templates and template parts, but rendering them in classic style php templates.
For example echoing blocks with do_blocks() in a classic php template, and leaving out the equivalent FSE html template.

If this will be possible, I could potentially see some theme authors offering a premium version that "unlocks" the Site Editor with the html templates only included in the premium version.

Yes, that should be possible. Theme-authors can start converting classic PHP template-parts to block syntax, place them in block-template-parts/*.html files, and then render them via PHP. You can even add a proxy function in your theme to make the process easier...

function my_theme_get_html_template_part( $relative_path ) {
	$path     = get_theme_file_path( $relative_path );
	$contents = file_get_contents( $path);
	echo do_blocks( $contents );
}

and then call it inside your PHP templates like my_theme_get_html_template_part( 'block-template-parts/footer.html' );.

The only thing that we first need to resolve is this issue: #28744 so that classic themes can use blocks that are currently only available in an FSE context.

[aristath]

I've been trying to figure out ways to handle classic themes and how we can allow users to create a new template regardless of whether their theme is an FSE theme or not. I have a draft PR in #29298 where I am experimenting and the logic I'm exploring is simple: If the user likes theme A but wants to build their own, custom frontpage, they should be able to do that without affecting the rest of the templates - which will continue to be inherited from the theme.
The draft PR is just a POC to see if it's possible, so there are a lot of missing pieces. However, I think that if we discuss the details and come up with a plan we can actually do it so that WP5.8 can include an FSE MVP.

With that draft PR you can now do the following:

• Enable any non-FSE theme
• Enable the FSE experiment
• Go to the site-editor
• Add a new template for index/frontpage/etc

All theme templates work like they are supposed to, and the author can create custom templates.

[mtias]

Thanks for starting this discussion!

There are a few things that I'd like to first touch upon. We should make a distinction between the technical support that would allow themes to have different ramps of support for blocks and the effects those hybrid states would produce on the UX. The last part is important to not offload the complexity incurred onto users while we remove it from developers. As an example, it could be rather confusing as a user if I end up in the site editor to edit the homepage but on a customizer view for some other archives; all in all not being clear to me why that is the case or even that these are indeed separate interactive paradigms.

In that sense, the gradual adoption makes sense from a theme developer standpoint but less so from the user perspective if it requires bouncing between different interfaces. We need to describe the different use cases properly to ensure they do make sense on their own.

It's also worth highlighting again that a very important part of the puzzle is what the widgets block editor and navigation block editor projects are currently aiming for: incorporating blocks in more places without changing the fundamentals of the theme. This allows turning existing parts of a theme into block areas as smoothly as possible.

I've been thinking about the notion of universal themes rather than hybrid. Universal themes would be themes that can be loaded in a classic context or block editor context without a problem. As a user, if I'm running a WordPress capable of understanding block themes, that's the interface I get (and the one I can customize), otherwise the regular theme files are used with its customizer integration. Hybrid would then be a tool for theme developers to gradually become universal themes if they want to.

In terms of infrastructure it does make sense to have the gradual slope of loading user templates, block templates, classic templates, in that order. It's what should happen to the editing UIs in the in-betweens that is less clear.

The “site-editor” admin menu should only show by default if the theme has a block-templates folder or if there are user-created block-templates.

This one needs a design review. So far the site editor has been kept as its own admin element in the sidebar, but that is not the intended end result. It should be absorbed into the Appearance menu and we need to consolidate the paths to edit (it'd still make sense to have direct access to things like Header, Navigation, even on block themes).

Some use cases and flows:

• Even if the hybrid states are doable, we might want to only introduce the site editor to users when a theme is fully capable of handling it. This might require a flag.
• Loading the site editing blocks in non-block themes. I think I lean on enabling these all the time across all contexts like @youknowriad mentions.
• Creating a new blank template for a page should be possible.
• Defining theme.json properties on classic themes.
• Loading PHP templates as server-rendered without interactivity on the site editor. Is this worth exploring at all?
• @bph example is an excellent case to account for. That template editor seems closer to the "Template editing mode within the post editor" milestone Site Editing Infrastructure and UI: Part 3 #27814, in that it doesn't necessarily require the presence of the entire site editor. WIP - Hybrid themes implementation #29298 looks like a good start for it, but I'm still unsure about the UX flows, which seems to be the main hurdle since technically speaking all current blockers seem surmountable.

[tomjn]

I've been thinking about the notion of universal themes rather than hybrid. Universal themes would be themes that can be loaded in a classic context or block editor context without a problem. As a user, if I'm running a WordPress capable of understanding block themes, that's the interface I get (and the one I can customize), otherwise the regular theme files are used with its customizer integration. Hybrid would then be a tool for theme developers to gradually become universal themes if they want to.

Can you elllaborate on this? I'm unsure what this means in practical terms, both from a user standpoint and a technical standpoint.

For example are you suggesting that a theme may work as themes currently do, but use FSE instead for say archive sections?

If so then how is it different from the original template hierarchies suggested? And how would such a universal theme not be considered a hybrid theme?

[mtias]

@tomjn no, I mean being able to have theme packages that can run in the two systems, so a theme builder can build up the support gradually, but the user would only interact with one.