Theme Customization

[urbanit]

Theme Customization: bootstrap front-end Liquid overrides from the admin UI

I've put together a new feature, OrchardCore.ThemeCustomization, that lets a super admin bootstrap front-end customization from the admin UI by cloning the active site theme's Liquid templates into Orchard's runtime-managed Templates store — without creating a new compiled theme, touching extension discovery, or requiring a rebuild/restart. Looking for feedback on the approach before pushing this further (CSS/JS overrides, broader template coverage, etc.).

How it works

1. Enable the OrchardCore.ThemeCustomization feature.

2. From Admin → Design → Themes, the active theme's card now shows a Customize button (only visible if you hold the ManageThemeCustomization permission).

3. That opens the Theme Customization dashboard, scoped entirely to the active theme — there's deliberately no "pick a different theme" dropdown. Initializing here is a one-click action.

4. On initialize, the feature clones the theme's supported Liquid templates into the Templates store — either all at once, or you initialize first and clone template-by-template afterward.

---

5. Editing a cloned template hands off to the normal Template editor you already know.

6. If you switch the active site theme afterward, the dashboard tells you your customization is now stale rather than silently mixing markup from two themes.

[urbanit]

I can make a demo if anyone is interested :-)

[hishamco]

Sure, @urbanit, can we chat on Discord if it's possible

[Piedone]

Yes, please demo it on Tuesday!

[hishamco]

Only Liquid :(

You can demo it to see it in action

[Piedone]

Very cool!

The theme can also have a base theme, in which case you'd need to initialize Templates from that as well (digging recursively as long as this dependency chain goes).

Also, something needs to happen if the theme uses Razor (or anything other than Liquid), at least the button be greyed out with a note on this.

[urbanit]

Update: from Theme Customization to Assisted Templates

Thanks for the feedback on Theme Customization. I took the idea further, and it changed shape along the way. It's now a PR to main: an opt-in Assisted Templates feature (OrchardCore.Templates.Assisted) inside the Templates module, rather than a separate OrchardCore.ThemeCustomization module.

How it changed from the original idea

1. From a theme dashboard to the Templates lists. Theme Customization had its own entry point, a Customize button on the active theme's card, which opened a separate dashboard. In the end, the place people already go to override a shape is Design > Templates. So the tools sit there, next to Add Template, and the edited templates are the ordinary templates, edited in the usual Template editor.

2. From "the active theme" to template sources. The first version only knew one source: the active theme. Templates also come from the modules, e.g. most of the content parts and fields, so the lists are built on an ITemplateSource abstraction with two sources, shown as a button group:

• Theme Templates: the templates of a theme, including its base themes.
• Feature Templates: the templates of the enabled features, all of them or one at a time, with the theme or feature that overrides each one.

Other modules can add a source.

3. From "no theme dropdown" to a theme selector. The original dashboard was deliberately scoped to the active theme. In practice it's useful to read the templates of another theme, e.g. before switching to it. So there's a theme dropdown, shown even with a single theme. Only the active theme's templates can be cloned, since those are the ones in use; the others can be viewed.

4. Razor templates as a reference. The original only handled the Liquid templates it could clone. Most module templates, and many theme templates, are Razor. They're now listed too and can be viewed as an inspiration to write a Liquid template with the same name, with a Create override button.

5. From "initialize" to per-template clone, with bulk actions. There's no initialization step anymore. Each Liquid template has Clone, and bulk actions clone, reset or delete several at once.

6. From a "stale" warning to monitoring each template. Instead of marking the whole customization stale when the theme changes, each cloned template has a status:

• Cloned: unchanged since it was cloned.
• Edited: edited since it was cloned.
• Source changed: the theme's file changed since it was cloned, e.g. after an update. Reset brings the local template back to the theme's version.
• Cloned from another theme: the template came from a theme that is no longer the one listed, so it isn't compared to it.
• Overridden: a template written by hand, not cloned.

The lists can be filtered by status, by language (Liquid or Razor), and, for the features, by what the templates render (front end or admin).

7. The admin too. The same lists are on Admin Templates, for the admin theme and the admin templates of the features.

8. Alternates. The hardest part of overriding a shape is knowing its name. For a template, Alternates lists the alternates of its shape for the site's content types, parts and fields (e.g. Content__BlogPost, BlogPost__Subtitle, TextField_Summary), with the content types and display types each one applies to, to create or clone a template for them.

9. Inspect Content. Pick a content item, or use Inspect templates in its actions menu, and see the shapes it renders in a display type, as a tree, with the template rendering each of them and all their alternates, the most specific first. That includes those of this item only, like Content__Alias__[Alias] and Content__Slug__[Slug]. The template rendering a shape can be viewed and, if it's Liquid, cloned from there.

10. No new permission. Instead of ManageThemeCustomization, it uses the existing Manage Templates and Manage Admin Templates permissions, plus Manage Liquid Templates.

11. Opt-in. It's a feature of the Templates module, not enabled by default.

Screenshots

The opt-in feature, in the Templates module:

The Templates list: the sources and Inspect Content next to Add Template:

Theme Templates: the active theme by default, with its file, language and status:

Cloned templates are monitored: one unchanged, one edited since it was cloned:

Viewing a theme template:

The alternates of the Content shape for the site's content types:

Feature Templates: Razor templates of the modules, to view and override:

The same on Admin Templates, for the admin theme:

Inspect Content on a blog post: the shapes, the template rendering each one, and their alternates:

The same content item as the admin renders it:

Inspect templates in the actions of a content item:

Known limitations

These are listed in the PR and left for follow-up:

• Placement: the front-end inspection renders the content item in the admin, so a site theme's placement.json isn't applied.
• Theme markup: shapes a site theme template renders in its own markup aren't listed.
• Admin side with Admin Templates off: the admin lists can still be opened by URL when Admin Templates is disabled, even though its templates aren't used then.

Feedback welcome, especially on the user journey and on what other sources or suggestions would help.

[hishamco]

You can link that into your related PR

[urbanit]

Related PR: #20154