Description

Since the introduction of block themes, the mental model has been that these themes provide interconnected entities (templates, styles, patterns) that the user can edit in the UI.

This mental model has proven challenging. The main problem is that from a user’s perspective, the difference between theme entities and user-created ones is blurred. We show templates from files and database ones in the same list. This means we have to create a custom abstraction that refers to files in some situations or custom post types in others.

Other challenges include:

• Losing access to edited user templates when switching themes, because they’re theme-specific.
• Losing template revisions when users click “reset template customizations.”
• “Reset template customizations” has proven to be a hard-to-understand interaction for users.
• Enabling use-cases like creating and switching alternative templates (like selecting a front page template) becomes difficult.
• We can’t create a paginated REST API for templates because pagination and filtering need to merge them from the database and files or PHP registration.

Proposal

We can address these problems for the future by adapting our mental model regarding these theme-provided entities.

Rather than users editing theme provided entities, this proposal explores creating custom ones and assigning them as replacement to the default provided ones.

In simpler terms for templates, it means:

• Users can create templates, name them, and assign them to the “template hierarchy.”
• By default, themes’ templates are “auto-assigned” to the template hierarchy slugs, acting as fallbacks.
• Users can use theme-provided templates as starting points for creating custom templates.

The biggest UX impact for existing FSE users and the site editor are:

• We must render the default templates from themes in a non-editable but “forkable” list.
• User templates will be displayed in a separate list from registered ones. This eliminates confusion in the current template list with some selectable items having bulk action, while others don’t.
• Users can freely assign and modify templates to specific hierarchy slugs.

This change automatically resolves the mentioned challenges and issues:

• User-created or edited templates will persist when the user switches themes.
• Users can reset the default theme’s templates as active.
• The confusing “reset template customization” action is no longer needed.
• You can mix and match templates from different sources, and show templates from multiple themes or template packs.
• Switching active front pages or templates becomes easy.

Technically, this is not a significant change compared to what exists today:

• A new site option is needed to store the “active template hierarchy slugs”. Think of it as an associative array where the keys are template slugs, and the values are the template id. If no id is assigned, the default theme template is used.
• Switch from the existing REST API endpoint for “templates” to the default Core post endpoints to fetch and edit them.

For backward compatibility:

• When this behavior is enabled, a simple database upgrade migration is needed to fill the “active template hierarchy slugs” site option using the existing user templates.
• The current template endpoint will remain for retrieving registered templates, and editing capabilities can be deprecated. The simpler post endpoint will be used for user templates.
• What about other entities (template parts, patterns, and styles) from themes?

Applying the same mindset makes implementing desired features for these entities easier. Examples unlocked:

• Unifying patterns and template parts (areas or slots support for patterns and phasing out template parts)
• Allowing pattern overrides in themes
• Creating and editing style variations
• Assigning style variations to pages and templates.

(This proposal is from both me and @ellatrix)