Skip to content

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

  1. Add templates/<theme>/<path>.html. A new storefront page goes in templates/nova/ first; a layered theme only adds its own copy to restyle it.
  2. Return the theme-relative name from the controller — "forgot-password/forgotPassword", never "nova/forgot-password/forgotPassword". A leading slash is stripped, but omit it.
  3. Reference fragments theme-relatively too: ~{fragment/head :: head(...)}.
  4. 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's fragment/icons.html if one exists — and fails if that file lacks ccVisa. 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 in fragment/brock-icons.html for exactly this reason).
  • Asset paths come from the ThemeContext, not the template folder. Brock's cssPath / jsPath / imagePath point at Nova's asset folders, so every Nova template and extension script it falls back to keeps loading its CSS/JS; Brock's own brock.css / brock.js are 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 in WebMvcConfiguration) 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 in ThemeAssetPaths, which AssetUrls uses 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):

<a th:href="@{${#categories.collection(child.seoName)}}" th:text="${child.name}">Category</a>

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.