Theme Resolution¶
Customer-facing templates live under a theme prefix: templates/nova/product.html,
templates/brock/product.html. Controllers never name the theme; they return the theme-relative
view name ("product", "forgot-password/forgotPassword") and a chain of Thymeleaf resolvers
inserts the theme.
Nova is the root theme. It is the only theme with overrideTheme: false, and every other
storefront theme is an override theme layered on it, directly (Brock, Depot, Ridge, ...) or through
another theme (Bistro and Tend on Brock). So every storefront template must exist in templates/nova/;
there is nothing below it.
The resolver chain¶
BadgerSpringResourceTemplateResolver (web) runs four legs, each with checkExistence=true so a
miss falls through to the next:
| Order | Leg | Resolves |
|---|---|---|
| 0 | override | <templatePath>/X, only when the theme is an override theme |
| 1 | base | <baseThemeTemplatePath>/X (override themes; nova if the record names no base) or <templatePath>/X (non-override) |
| 2 | second base | <secondBaseThemeTemplatePath>/X, only for an override theme that names one; every other theme declines |
| 3 | default | nova/X (DEFAULT_THEME_NAME), whatever the theme is |
The theme comes from siteContext.templateTheme (a ThemeContext): templatePath,
baseThemeTemplatePath, the optional secondBaseThemeTemplatePath and the overrideTheme flag. The optional family and sortOrder fields
only affect how the admin picker groups and orders themes, not resolution; see
Choosing a Theme.
A request with no site, or a site with no theme, resolves against nova/ too: the override and
second-base legs decline and the base leg uses DEFAULT_THEME_NAME.
For a theme layered on Nova, legs 0 and 1 give "the theme, then Nova". A theme layered two deep (Bistro or Tend on Brock on Nova) names its second base, so it resolves Bistro → Brock → Nova.
The pattern library's PatternTemplateResolver has the same four legs, but reads the theme from the
render's template resolution attributes rather than the request (see
Pattern library). Its chain() lists the folders a theme looks in,
with declining and repeated legs left out: [bistro, brock, nova] for Bistro.
Emails don't use this chain: they aren't themed. See Transactional Email.
Why the default leg exists¶
For a correctly set-up theme the default leg only repeats Nova, which the base or second-base leg has already tried. It is there for sites whose stored copy of their theme is stale. A site renders from the copy of its theme embedded in the site document, so a site still pointing at a theme that no longer ships (a non-override theme other than Nova, or a base folder that has gone) would otherwise fail to resolve any page, and Thymeleaf raises
TemplateInputException: Error resolving template [...], template might not exist
or might not be accessible by any of the configured Template Resolvers
which surfaces to the visitor as a 500. The default leg degrades those to Nova instead.
Retired themes are cleaned up by a system update rather than left to this leg:
2026-11-03-retire-bootstrap-theme.json (bean RetireLegacyThemes) made Nova the root on existing
databases (the theme records and each site's embedded copy), moved every site on a theme whose
templatePath isn't shipped to Nova, archived sites included, and deleted those theme records. That
removed the Bootstrap 4 theme and its Bootswatch skins, which used to sit below Nova as the last leg.
Adding a page to a theme¶
- Add
templates/<theme>/<path>.html. A new storefront page goes intemplates/nova/first; a layered theme only adds its own copy to restyle it. - Return the theme-relative name from the controller —
"forgot-password/forgotPassword", never"nova/forgot-password/forgotPassword". A leading slash is stripped, but omit it. - Reference fragments theme-relatively too:
~{fragment/head :: head(...)}. - If a layered theme has no version of its own, the chain falls back to its base and then Nova. That is expected, not a bug.
Nova's standalone account pages (login, register, forgot/reset/change password) share
nova/fragment/auth-head.html, which carries the <head> and the auth design-system CSS so each
page does not repeat it. The password pages use the whole head (authHead(pageTitle, pageDescription));
sign in and register (registration.html) write their own head for reCAPTCHA and the submit callbacks and
take only its styles, the inner authStyles fragment. A theme with its own auth-head (Atelier, Brock,
Depot, Spec, Diorama) re-skins all of these pages, so its copy must declare both fragments.
Themes layered on another theme (Brock on Nova, Bistro on Brock)¶
Any override theme can use another override theme as its base. Brock is overrideTheme: true with
baseThemeTemplatePath: nova, so a page resolves Brock → Nova (legs 0 and 1). Bistro is
layered on Brock: baseThemeTemplatePath: brock and secondBaseThemeTemplatePath: nova, so it resolves
Bistro → Brock → Nova (legs 0, 1 and 2). Tend is layered on Brock the same way. Two rules come with that:
- A theme's fragment file shadows the base theme's file of the same name, for every caller.
When a Nova template does
~{fragment/icons :: ccVisa(...)}on a Brock site, it gets Brock'sfragment/icons.htmlif one exists — and fails if that file lacksccVisa. So either re-declare every fragment the base theme's templates use, or give the new theme's fragments a new file name (Brock's icons live infragment/brock-icons.htmlfor exactly this reason). - Asset paths come from the
ThemeContext, not the template folder. Brock'scssPath/jsPath/imagePathpoint at Nova's asset folders, so every Nova template and extension script it falls back to keeps loading its CSS/JS; Brock's ownbrock.css/brock.jsare linked by path from Brock's head. - A theme asset the theme hasn't got comes from Nova's folder. An extension's stylesheet or script
(
cssLocation/requiresCSS,requiresJS) is addressed under the shop's theme folder, e.g./settBuilder/themes/ridge/css/extensions/socialLinks/social-links.css. When Ridge has no such file,NovaThemeAssetResolver(on the/settBuilder/**handler inWebMvcConfiguration) serves Nova's, as templates fall back to Nova. Themes don't copy Nova's extension assets; until November 2026 the build copied the Bootstrap theme's into every theme folder instead. The admin and shared folders don't fall back. The rule lives inThemeAssetPaths, whichAssetUrlsuses too, so a page asking for Ridge's copy of that stylesheet is given Nova's content-hashed copy (see Storefront Asset Build).
A theme layered on Brock does not copy Brock's head or footer; Brock leaves hooks in them, empty files that the
layered theme shadows with its own: fragment/themeAssets (extra stylesheets and scripts, after Brock's, in
the head) and fragment/footerNotice (a band at the top of the shared footer, ui/footer.html; Nova and Brock ship it empty). Bistro and Tend use both. Changing which theme
a site's theme is layered on, for sites that already have it, is a system update (RebaseTheme): a site
renders from the copy of its theme embedded in the site, so the update changes both the theme record and
that copy.
Controllers must return theme-relative view names¶
CheckoutController, DemoModeController and LoginAndRegistrationController used to return
siteContext.getTemplateTheme().getTemplatePath() + "/page-9-3" (and /demoLogin, /registration).
The resolvers then looked for <theme>/<theme>/page-9-3, which never exists; the view only rendered
because Spring Boot's own default resolver found templates/<theme>/page-9-3.html directly. Any
theme without its own copy of those templates got a 500 on checkout. They now return the bare name,
like every other controller, so the chain above applies.
A th:if on the same element does not guard a th:insert¶
Thymeleaf processes attributes in precedence order, and fragment insertion comes first:
th:insert / th:replace are 100, th:each is 200, th:if / th:unless are 300,
th:with is 500. So on a single element the fragment's parameters are evaluated before any
th:if on that same element can remove it:
<!-- Broken: product.images[0].url is evaluated even when hasImage is false -->
<div th:if="${hasImage}"
th:insert="~{fragment/responsive-image :: responsiveImage(${path}, ${product.images[0].url}, '')}"></div>
A product with no images gives images == null, so that expression throws
EL1012E: Cannot index into a null value and the whole page 500s — not just the one card.
This took out every Brock listing on a demo tenant the first time the theme was switched on.
Put the guard on a wrapping th:block instead. A parent's th:if is resolved before its subtree is
processed, so nothing inside is evaluated:
<th:block th:if="${hasImage}">
<div th:insert="~{fragment/responsive-image :: responsiveImage(${path}, ${product.images[0].url}, '')}"></div>
</th:block>
Making the parameter itself null-safe (a ternary, as Nova's card does) also works. th:with on the
same element is fine to guard with th:if, because 300 runs before 500 — only fragment insertion is
affected.
Linking to a collection: #categories¶
Templates never build /collection/... themselves. They ask #categories (CategoriesDialect):
CategoryLinkService decides where the link goes. On a site whose categories come from its
collections, the answer is /collection/<seoName>. On a site whose categories come from the
merchandising tree (category-navigation-source=MERCH_TREE), it is the canonical path of the
category that has replaced the collection, falling back to the collection's own page. Java code
that builds collection links (menus, Open Graph, share links, animation scenes) calls
CategoryLinkService.collectionPath directly.
#categories is made once per page render from CategoryLinkService.routesFor(site). That reads the
shopper's hidden collections and the site's settings once, and works each collection's link out once, so a
menu that links the same collections in the bar and the drawer costs one lookup per collection, not one per
link. Java code that links many collections in one go can use routesFor the same way; don't keep its
result beyond that work.