Who this is for. Theme developers, and whoever plans and estimates the work on a site. After this page you will know why a template on its own does nothing, the order in which a new kind of page is built, and what that order means for a plan.

The rule

A page is rendered with the layout its live revision uses, and the layout names the template. A template file in the repository that no layout names is never used to render a record, however correct it is. Components work the same way: a component's template renders only because a component layout points at it.

The exceptions are the templates the platform asks for by a fixed path. They work without a layout of their own:

  • the error pages under errors/, such as errors/not-found.html;
  • a module's default template, used for a record whose revision has no layout, such as pages/pages/show.html for pages;
  • templates under my-account/, which member-area URLs map to directly: /my-account/requests/show renders my-account/requests/show.html;
  • partials that other templates pull in with include or extends;
  • templates that jobs render, such as the body of an email or of an HTTP request.

Everything an editor builds with, every page, post and component, starts with a layout.

The order a new kind of page is built in

  1. Plan the layout. Decide the areas editors will fill in, the input type of each and their names. Templates and integrations will use those names, so this is the decision that is expensive to change later.
  2. Create any input type the site lacks, such as a select of design options, under Customization › Input Types.
  3. Deploy a placeholder template at the path the layout will use. The admin's layout form lists only the template files it finds on the server, so the file must be deployed before a layout can point at it.
  4. Create the layout under Customization › Layouts: choose the template and the controller, and add the areas.
  5. Create a record that uses the layout, fill it in and publish it.
  6. Write the real template, reading the areas, and deploy it.

Your first page, end to end walks these steps on a real site, one page each.

What it changes in a plan

  • Every new kind of page has an admin step, on every site that needs it. The layout, its areas and any new input types are database records, and a deploy does not create them. Decide who creates them on production, and when.
  • Editors can start before the design is finished. Once the layout exists, content can be entered against the placeholder while the real template is written.
  • Area names are an interface. Agree them early with whoever writes the templates, the integrations and the content. Renaming a layout area later means changing everything that reads it.
  • Estimate the model as well as the markup. A design with ten kinds of section is ten component layouts, each with its areas and its template, before the first page is assembled.