Guide 04 · Developer docs

Input types, layouts, components and images

The platform's central abstraction, in one line: an input type defines what an editor can enter, a layout area binds one input type to a named slot, a layout groups areas and points at a template, a record or component holds the content for each area, and the template reads it back. Read this book straight after the template languages.

L1–L3
Unit 03 · Layouts

What a layout is, field by field

Layouts Page 6 of 45 Updated

A layout joins one template file to a set of layout areas and says which records may use it. Every field of the layout form and what it affects, the template path and how it fails, where the layout areas are defined, and custom fields on the layout itself.

Who this is for. Whoever creates layouts under Customization › Layouts, and the developer whose template a layout points at. After this page you can fill in a layout form knowing what each field changes, and find out in two minutes why a layout renders the wrong thing or nothing.

The layout form

FieldWhat it affects
Name (required)What editors see when they choose a layout or add a component, and what the admin lists. Free to change.
IdentifierA stable machine name for the API and integrations: see Site scoping, identifiers and hiding.
External IDAn id from another system, for imports that must find the same layout again.
SiteOne site, or every site of the client when left empty.
ControllerWhich kind of record may use the layout, or None (Component) for a component layout. The single most important field: see Page and component layouts. The form does not show it for templates under components/.
TemplateThe file that renders the layout, chosen from a tree of the template files on the server.
Areas, Area groupsThe fields editors fill in, and the sections of the editing form: the unit Layout areas, groups and attributes.
Image (Categorization tab)The thumbnail authors see when adding a component.
Category (Categorization tab)A place in the tree of layout categories. Both are on Thumbnails, categories and the author's picker.
Custom fieldsShown when the site defines custom fields for layouts (below).

The template path

The layout stores the template as a path relative to the theme's templates/ folder, such as pages/pages/landing.html, and nothing more: there is no link to the file. The path is resolved like any template, in the site's engine, first in the site's own templates and then in the platform's. Moving or renaming the file therefore breaks every layout that names it, and the layout form will not show the file until it is on the server.

When the file is not there:

  • Smarty prints Template not found: pages/pages/landing.html where the page or component should be, and the response is still HTTP 200;
  • Twig raises an error, so the page fails with the site's error page;
  • a component layout with no template set renders nothing. A page whose layout has no template falls back to the controller's default template, such as pages/pages/show.html.

The two-minute diagnostic: open the layout and copy its template path; check that exact path, with its case, is in the branch the environment deploys (git ls-files templates/pages/pages/landing.html); check the environment's last deploy includes the commit; and check, in the record's editing form, that the record uses this layout at all. A template can ask the same question of a layout with hasExistingTemplate(), which looks only in the site's own templates/ folder.

Template code 
{$layout = $page->getActiveRevision()->getLayout()}
<!-- layout {$layout->getName()|escape}: {$layout->getTemplate()}, {if $layout->hasExistingTemplate()}found{else}missing{/if} -->
{% set layout = page.getActiveRevision().getLayout() %}
<!-- layout {{ layout.getName()|e }}: {{ layout.getTemplate() }}, {{ layout.hasExistingTemplate() ? 'found' : 'missing' }} -->

Where the areas are defined

A layout's areas are created on the layout form, one at a time, each with a name and an input type: the unit Layout areas, groups and attributes covers every field. Many teams also list each template's areas and their input types in a comment at the top of the template, so that whoever creates the layout on another environment knows what to add. Either way, the layout in the admin is the record of truth.

Custom fields on a layout

A layout can carry custom fields, defined for layouts under Customization › Custom Fields. They hold facts about the design, the same for every record that uses the layout: the number of grid columns, the stylesheet bundle it needs, whether it shows a sidebar. A template reads them from the layout:

Template code 
{$layout = $page->getActiveRevision()->getLayout()}
{$columns = $layout->getCustomFieldText('gridColumns', '12')}
<div class="grid grid--{$columns}">...</div>
{% set layout = page.getActiveRevision().getLayout() %}
{% set columns = layout.getCustomFieldText('gridColumns', '12') %}
<div class="grid grid--{{ columns }}">...</div>

In a component template, the layout is $component->getLayout() (component.getLayout()). The rule for choosing: if the value is the same for every record on the layout, it is a custom field on the layout; if an editor should be able to set it per record, it is a layout area, usually an attribute.

Go deeper
GuideTemplate resolution order How-toCreate your first layout and template, from the admin to the repo FAQMy template change is not appearing on the site FAQA record shows the wrong template ReferenceLayouts

Was this page helpful?

Your answer goes to the docs team.