Who this is for. Theme developers. This is the step people miss: after it, you will know why a template file on its own does nothing, and where to look when a page renders with the wrong template.
The record's layout, not the controller
A controller does not choose the template. Once the page's show controller has found the page, it reads the layout of the page's live revision and renders that layout's template. Only when the revision has no layout does the controller's own default apply: pages/pages/show.html for pages.
One controller, many templates
On this documentation site, one controller, Show Page under Pages, renders all of these. Each page names a different layout, and each layout a different template:
| URL | The page's layout | The layout's template |
|---|---|---|
/ | Hub Composed | pages/pages/hub-composed.html |
/developer-docs | Hub Developer Docs | pages/pages/hub-devdocs.html |
/developer-docs/reference | Hub Reference | pages/pages/hub-reference.html |
/changelog | Default layout | pages/pages/show.html |
To change how a page looks, an editor can give it another layout; nothing in the repository changes. To change how every page on a layout looks, you change that layout's template; no record changes.
A record with no layout
Each show controller has a default template that it uses when the record's revision has no layout: pages/pages/show.html for pages, and a path of the same shape in each module, such as blogs/posts/show.html for blog posts. The platform ships none of these for the public site. Your repository must have them for any record that can end up without a layout, or the page shows Template not found on Smarty and an error on Twig.
Where the file is looked for
Whatever path the layout names is looked for in the site's templates/ folder first, then in the platform's own templates. A site file at the same path as a platform template therefore replaces it. Template resolution order has the detail.
When an editor changes a page's layout
The content of an area is carried over to the new layout when the new layout has an area with the same name. Content in areas the new layout does not have is not carried over. Agreeing area names across layouts, heading and body on every page layout, makes switching painless.