Allow usage of block based "template parts" without using block based "templates"

[fabiankaegy]

What problem does this address?

Jumping all in on Block Based Themes can be quite difficult & disruptive. Especially on a legacy theme that has loads of customizations that currently are not feasible within a block based theme. There may be new areas of the site though or specific areas of the site where it would be interesting to use the new tools to build just a part of the theme in a block based manner.

Like for example a site that wants to build just the site footer using a block based template part.

What is your proposed solution?

Allow the usage of block based "template parts" without having to also allow block based "templates". In that case the "Editor" (previously Site Editor) would only display the "Template Parts" and not allow the creation of "Templates". And in the themes traditional footer.php file the theme author could render the block template part like so:

echo do_blocks( '
<!-- wp:template-part {"slug":"footer","theme":"fse","tagName":"footer","className":"site-footer","layout":{"inherit":true}} /-->
' );

In an ideal case theme authors would also be able to filter whether or not editors should be allowed to manually create their own "template parts" or whether only the ones provided by a theme are available.

Providing this template part first approach to adopting FSE would open the door to many more use cases that currently are not jet ready to jump all with their full content.

Note: This conversation was started in the #fse-outreach-experiment channel in the WordPress Slack

[annezazu]

@priethor just wanted to put this on your radar as this might be another great idea to consider for gradual adoption measures.

[mtias]

This is precisely what the universal themes exploration was doing on the side. You'd end up with <?php echo gutenberg_block_template_part( 'header' ); ?> calls in your PHP theme.

It's something we could formalize into a core API (i.e. get_block_template_part( $slug )) but there's some decision that need to happen first around how coupled a template part is to a theme, which is up for revision.

[fabiankaegy]

@mtias is there a ticket where the discussion around how coupled a template part is to a theme is being tracked? Would love to link it here to ensure we have a clear understanding of the dependencies.

[aristath]

In WP 5.9 we already added 3 new functions to do these things: block_template_part, block_header_area and block_footer_area. You can see them in https://github.com/WordPress/wordpress-develop/blob/d085349cf5760294d1bdbc3f01e30a483d921f5d/src/wp-includes/block-template-utils.php#L872-L903 👍

[fabiankaegy]

@aristath That is very cool! Thanks for sharing :)

So the main thing that this ticket is asking then is whether we can activate the site editor for template parts alone without needing to enable full on templates

[mtias]

@fabiankaegy yes, correct, we are missing the ability to enter the site editor in the "focused template part" mode directly. We have the building pieces mostly in place, we just need to enable it for classic themes. It should be a good area of work for 6.0. A classic theme should not need to use full block templates to benefit from block template parts and a UI to manage them. The things to consider are mostly around the information architecture and access points.

[graylaurenm]

I agree that this would be an excellent stepping stone between classic themes and FSE and it's something my team is looking for.

In the meantime, we're using a custom post type as a stop-gap solution, which presents its own challenges.

[mtias]

It seems we need some more documentation on how to use these from a PHP template.

[ALJ]

Fabian's proposed suite of features for a template-part-first adoption of Full Site Editing is the one thing I'm most excited about in WP's near future. I understand v6 is now in feature freeze, but I haven't yet seen any work towards this:

... activate the site editor for template parts alone without needing to enable full on templates

My current experience of adding an index.html file in /templates is an inoperable white screen for a site editor, and then the baffling realization that I have to give up any bespoke front-page.php in order for the site editor to even load successfully. The system is unusable to me as-is (or maybe I'm ignorant of how it wants to be used).

The block editor is amazing in many ways, but I can't get fully behind it when I feel it's removing things I enjoy having. I would love the ability to give content editors controlled "block editor windows" into their sites in the context of classic templating 👍

[coreyworrell]

The block editor is amazing in many ways, but I can't get fully behind it when I feel it's removing things I enjoy having. I would love the ability to give content editors controlled "block editor windows" into their sites in the context of classic templating +1

This exactly. It at least would make adopting FSE easier than an all-at-once or all-or-nothing approach. The Appearance > Editor screen would be great to have for just template parts and global styles, while still allowing templates themselves to be in PHP.

[azaozz]

This is a great idea that will help the move from classic themes to FSE. Been thinking how this can be implemented to support the intended use, and to discourage "overuse", deep-nesting, and similar.

Can easily see a classic theme that would use blocks in a hard-coded template part for the header, footer or sidebar. Thinking this would work and look great. That basically means the "widgets" in these areas are now native blocks with no restrictions!

On the other hand thinking that this should be limited to specific areas: header, footer, sidebar(s), main content. Nesting of hard-coded template parts may turn out to be pretty hard to support and maintain. Imagine having to support deep-nested blocks styles/CSS that may be changing from time to time, or scripts that are connected to or depend on specific blocks.

[carlomanf]

Related: #41119

[mtias]

The biggest challenge here is going to be how to give access to an interface for editing these parts. I think the most straightforward approach would to add a "Templates" item under Appearance on non-block themes when they make use of parts.

• It's easy for a PHP template to use a block template part. The tricky part is how should it inform that it's doing so for the admin to expose the relevant UI?
• The relevant UI could be just a wp list view of the template post type. When editing an entry we should load a site-editor instance with just that template part in focused mode.

It'd be good to map a quick design flow on how it might work.

[coreyworrell]

@mtias

It's easy for a PHP template to use a block template part. The tricky part is how should it inform that it's doing so for the admin to expose the relevant UI?

I assume a scan of the HTML files in theme/parts like it does for FSE would suffice?

[carlomanf]

It's easy for a PHP template to use a block template part. The tricky part is how should it inform that it's doing so for the admin to expose the relevant UI?

I assume a scan of the HTML files in theme/parts like it does for FSE would suffice?

The files scan is only performed when the site editor is loaded. To expose the UI in the admin menu, a more lightweight check would be needed, since it needs to run on every admin page load. I think current_theme_supports( 'block-templates' ) is appropriate in this case.

[ALJ]

@mtias

a PHP template to use a block template part. The tricky part is how should it inform that it's doing so for the admin to expose the relevant UI?

Could the existing templateParts key in theme.json be expanded to provide this? As an example of an existing valid templatePart with an imaginary expanded one:

{
  "version": 2,
  "templateParts": [
    {
      "name": "header",
      "title": "Header",
      "area": "header"
    },
    {
      "name": "large-overlay-message",
      "title": "Large Overlay Message",
      "area": "overlay",
      "isolatedEditor": { 👈 This makes the part editable in isolation in Appearance > Editor > Template Parts.
        "allowedBlocks": [ 👈 Template parts should have top-level block restrictions.
          "core/heading",
          "core/paragraph"
        ],
        "layout": {
          "contentSize": "768px" 👈 This sets an initial editor width.
        }
      }
    }
  ]
}

All of this functionality would be so much more useful with a way to restrict top-level blocks to the intention of the template part. Something like:

<!-- wp:template-part {"slug":"tiny-greeting","tagName":"aside", "allowedBlocks": ["core/heading", "core/paragraph"]} /-->

[critterverse]

I think the most straightforward approach would to add a "Templates" item under Appearance on non-block themes when they make use of parts.

Sharing a quick flow for this appoach:

If we wanted to provide a way for users to set/change template parts from the post editor, a “Templates” panel could be added to the document settings tab for specifying what template part should appear in a particular area:

Would still need to think through how a change could be saved in that case (which would normally be saved to the Template) but wanted to check in to see if this aligns with what folks have in mind so far!

[fabiankaegy]

The idea of allowing users to change which header/footer template should get used is interesting and not something I have previously considered. I can see how that would be useful for some folks.

From my perspective especially in more controlled client environments, it would not even be necessary to allow editors to create new template parts. Since they would always need to get used in a PHP template first and so the utility of a template part that doesn't get used is limited.

The feature set that would be super useful for these themes that only start to gradually adopt FSE is showing uses the various templates that the theme supports / has already defined and then allowing the users to modify the contents of each of these various templates.

[ALJ]

If we wanted to provide a way for users to set/change template parts from the post editor, a “Templates” panel could be added to the document settings tab

@critterverse Considering the label "Template" is pulling a lot of weight in WordPress at the moment (block templates, page templates), should we use the already-defined "Template Parts", instead? Or is it intentional to refer to "Template Parts" as "Templates" in the context of PHP themes?

I'll echo Fabian's note: for the controlled client sites I work on, it's not necessary to allow editors to create new parts. The most important thing is to provide a way to expose the block editor to ad-hoc theme-defined "Template Parts".

Although not essential, defining (1) allowedBlocks and (2) an initial editor width, would make this feature much more useful to smoothly guide content editors when editing the template parts.

[critterverse]

Good to know about not needing a pathway to create new Template Parts, thanks @fabiankaegy and @ALJ. I've gone ahead and removed that aspect from the mockups above.

[colorful-tones]

This seems like it would be quite valuable for builders to have in order to ease the transition from classic theme to block themes.

I'll echo Fabian's note: for the controlled client sites I work on, it's not necessary to allow editors to create new parts. The most important thing is to provide a way to expose the block editor to ad-hoc theme-defined "Template Parts".

Agree. It seems unwarranted to allow editors to create new template parts if there is no template to output that template part in the theme. (How many times can one say "template" 😵 ) It would just lead to unnecessary confusion.

@critterverse 's designs makes sense to me. I'm going to go ahead and remove the Needs Design label for now.

[georgestephanis]

👋

I'd had something come up in my tinkering that led me down a hole to see what is / isn't currently possible with the status quo on t his front.

The full brain dump as I investigated is in Slack here, if anyone would like a peek behind the curtain: https://wordpress.slack.com/archives/C02QB2JS7/p1657158514746249

In short, unless some filters are added, opting in to enabling template partials from outside of the theme seems non-functional, as even if there were a filter that enabled adding your own template parts, it would all get shorted out and invalidated by the WP_Theme_JSON_Resolver::theme_has_support() check -- as if a Classic theme doesn't have a theme.json existing, the whole thing gets yeeted.

What I'd love to see here is a way for plugins to either use a function to register a partial, or a filter in a pinch, and also correctly attribute the "Added By" as documented here: https://github.com/WordPress/gutenberg/blob/33d84b036592a5bf31af05b7710f3b2b14163dc4/packages/edit-site/src/components/list/added-by.js#L165-L173 -- but that seems at first glance to just be currently for theme ones that are customized by a plugin, not originating in a plugin? I could be very mistaken, just looking at how the conditionals are checking for theme stuff there.

Anyway, more musings are in the linked Slack thread, and I'd love to be able to use the core concept of a "Template Part" to let folks use the FSE system to customize areas that could be slotted into Classic themes -- as I feel it could be huge to better drive adoption, as well as a more consistent pattern rather than some plugins shoving markup in options, some registering their own CPTs, and others just using Pages with hardcoded slugs to store stuff.

[georgestephanis]

Some of the AddedBy stuff in ^^ is explained in https://github.com/WordPress/gutenberg/issues/37401 where the template.theme would actually be the plugin slug

[Mamaduka]

Hi, folks

I decided to share my current progress for this feature - https://github.com/WordPress/gutenberg/pull/42729. All feedback is welcome ❤️

[fabiankaegy]

As a follow-up for this feature itself I've also created a new issue to add the ability to lock the root level of a template part #42775

[jasmussen]

Resharing a few high level thoughts from the conversation of a related PR:

• In classic themes, the appearance menu looks way different, with many more options
• Having a “Template Parts” item there which opens the block editor and allows limited editing, that’s cool!
• Using the isolated mode for it, as they are template parts, is also cool.

There is some potential for user confusion:

• A user of only classic themes switches to a new classic theme with template part support. In using the new feature, they might be confused by features which seem like they should work, but won't in this context, due to limitations that aren’t necessarily communicated.
• Or: a user of mainly block themes switches to a classic theme with template part support and sees this option instead of the site editor, also being confused by new limitations.

In both cases, there may not be a ton we can do, but it might also not be a big problem in practice. If it turns out to be, we could follow up with a minimal welcome-modal that explains the feature, just like the welcome modal for the site editor does.

[annezazu]

@Mamaduka how are you feeling about this work considering your WIP PR? Trying to check in ahead of feature freeze for 6.1 and this would be awesome to have progress on.

[georgestephanis]

Honestly, if possible I'd be delighted for this to only be enabled in the next version as a "A plugin can opt in to the UI and create its own links to its defined template part" -- without having core create the menu ui that could lead to the confusion referenced?

I'm much more interested in having this be something plugins and the like can opt in to a limited functionality of, and am 100% comfortable with saying they then need to define the UI routes to get to that page. They may want to add a link to it as a subpage on a custom post type instead of the Appearance menu, for example.

[paaljoachim]

What about customizing the Author bio box and the Comments section in a Classic theme? Perhaps these elements in some way could also be added into a kind of template area in Classic themes...

Currently one would need in a Classic theme to go to a post and create a new page template and add the blocks there. One would need to remember to switch from the default page template to the custom page template for every post. I would be better to use a more FSE approach to this aspect.

[fabiankaegy]

@paaljoachim These are exactly the things that I was thinking about for this. There are areas in classic themes that can benefit from block customizability. And currently, the jump to full-on block-based themes is too drastic. Therefore it would be great to be able to edit just parts of the website (template parts) using blocks :)

[fabiankaegy]

@georgestephanis I can see your point and think the idea of allowing developers to link directly to the template parts editor for a specific template part is really cool. That could definitely be an interesting exploration.

I personally think though that it would be more confusing than the template parts menu under appearance which brings you to the site editor template part list view. With that we have some more consistency with how it works in the other editors and also we expose all the various available template parts to the user. Which makes them much easier to discover.

Also, I think that since this feature is really primarily intended for themes (since it gets enabled via a theme supports flag and themes are where you ship the template parts) it should not rely on custom work done in plugins or a lot of custom PHP work to manually create the UI for the links to the template part editor.

Finally, I think that it would lead to a confusing experience if every theme would expose these links slightly differently. It would make switching themes even more confusing since the way you edit template parts works completely differently.

[Mamaduka]

@annezazu, PR is primarily stable. I need to do small follow-ups, but that's it. We can land the new Welcome modal, suggested by @jasmussen, separately.

@georgestephanis, I agree with Fabian that this feature shouldn't rely on 3rd-party plugins to expose UI.

[annezazu]

Awesome! Great work, @Mamaduka. As we spoke about via DM, let's get a call for testing in place asap when this lands.

[carlomanf]

Not sure whether this comment is better placed here or at https://github.com/WordPress/gutenberg/pull/42729, but I will put it here in case more people see it.

A potential issue with the implementation of https://github.com/WordPress/gutenberg/pull/42729 is that a theme might support both template parts and widget areas, meaning that both the Template Parts and Widgets submenu items are added to the Appearance menu. In this case, I expect it would be quite unclear to the average user why there would be two different destinations with very different interface designs, when both features apparently have the exact same purpose. Both support the inclusion of blocks, and both are rendered by the theme using a template tag. Whether the template tag is dynamic_sidebar or block_template_part is of no interest to the user.

There is already a consensus at #39270 that template parts will be the supplanter of legacy widget areas, but is more from the perspective of block themes that did not otherwise support widget areas. Allowing both to co-exist with noticeably different interface designs does not seem like a good outcome.

[fabiankaegy]

@carlomanf I agree that having both at the same time is not the best experience. I personally think of the two a bit different because in my opinion template parts are more powerful than widget areas since they conceptually give you more control over the layout of a section. (I know technically speaking you could do very similar things in block-based widget areas)

Since template parts are clearly the way of the future, and since this template part editor is opt-in only, I am of the opinion that this confusion isn't going to be a problem. And that we would limit ourselves if we would cut off the support for the more powerful template parts in classic and hybrid themes.

Having access to template parts in these themes is a great pathway for adopting more full site editing capabilities without having to jump all in.

[carlomanf]

I am of the opinion that this confusion isn't going to be a problem. And that we would limit ourselves if we would cut off the support for the more powerful template parts in classic and hybrid themes.

I think there are ways to lessen the confusion between template parts and widget areas without cutting off support for both at the same time.

• Why do they need to be accessed through separate admin menu items?
• Why do they need to use radically different interface designs?
• Why do they need to have different names?

[paaljoachim]

I am not totally sure that this issue should be closed, as it feels like a good place to discuss various solutions. @Mamaduka George has one PR that has now been merged, but there might be a few more that also needs to be created. I will reopen this issue. Let's keep discussing and continue iterating on solutions that come up. (If I am mistaken then please close the issue again.)

[mtias]

This should be closed for project tracking purposes as the main implementation is merged. Let's open follow ups to narrow down experience gaps or improvements.

@carlomanf I think that's a great point. It's also true generally for customizer / site editor or customizer / styles. The semantic space is generally the same between widget areas and template parts. We had on the backlog the idea of introducing a "sidebar" area next to "header" and "footer" which would increase that overlap.

Another point of reference is how when you use the post editor you don't need to choose, from a user perspective, different entry points for blocks or classic editing. It generally just works depending on how the site and content is configured. Ideally all the phase 2 tools would also work in a similar way.

[mrleemon]

Are you aware of this?

https://make.wordpress.org/core/2022/10/04/block-based-template-parts-in-traditional-themes/#comment-43901

[Mamaduka]

@mrleemon, I saw that comment this morning.

It looks like the shortcodes issue was missed when the block_template_part method was introduced in WP 5.9.