Layout template file

The layout template file defines how the layout renders with the content zones.

Template file example

The following example shows a simple three-column layout template:

<div class="d-flex flex-row py-2 px-0">
    {{#if zones.lhs}}
        <div class="p-2 w-25">
            {{zones.lhs}}
        </div>
    {{/if}}
    {{#if zones.main}}
        <div class="p-2 w-50">
            {{zones.main}}
        </div>
    {{/if}}
    {{#if zones.rhs}}
        <div class="p-2 w-25">
            {{zones.rhs}}
        </div>
    {{/if}}
</div>

Template structure

The template contains HTML wrapped around Handlebars expressions.

The placeholders for each of the content zones are:

{{zones.name}}

For this example, the three content zones are referenced:

{{zones.lhs}}
{{zones.main}}
{{zones.rhs}}

These names match the three zone definitions in the configuration file.

Conditional zone rendering

Wrapped around each content zone reference is code similar to:

{{#if zones.main}}
 {{zones.main}}
{{/if}}

This checks that the content zone exists. If it does, the system renders the zone.

You can also include an else clause in the code:

<div class="{{#if properties.showSidebar}}w-75{{else}}w-100{{/if}}">

Handlebars helpers

In addition to standard Handlebars logic, you can use several helpers to implement complex conditional logic and string manipulation in your layout templates. These are particularly useful when working with Layout properties.

ifEq: Provides a simple object comparison. It uses strict equality (===) for comparison.

It works with strings, numbers, booleans, null, and undefined.

It renders the inner block if the two values are equal. Otherwise, renders the inverse block (if provided).

The syntax to use the ifEq helper is:

{{#ifEq properties.theme 'dark'}}
  <div class='dark-theme'>
{{else}}
  <div class='light-theme'>
{{/ifEq}}
    {{{zones.content}}}
  </div>

ifNotEq: provides the inverse of the ifEq simple object comparison.

It renders the inner block if the two values are not equal. Otherwise, renders the inverse block (if provided).

{{#ifNotEq properties.backgroundColor 'light'}}
  has-background has-background-color background-color--{{properties.backgroundColor}}
{{/ifNotEq}}

toLowerCase

Converts a string to lowercase.

The following example shows how to normalize CSS class name values. For instance, if a layout configuration file has a sidebarPosition property with available values of Left and Right, the toLowerCase helper ensures the correct CSS class names are output without capitalization:

class='sidebar-{{toLowerCase properties.sidebarPosition}}'

toUpperCase

Converts a string to uppercase.

The following example shows how to create uppercase labels or badges from a status property:

<span class='badge badge-label'>{{toUpperCase properties.status}}</span>

stringify

Converts an object or value to a JSON string.

The following example shows how to display debugging information by outputting an object’s structure in an HTML comment:

<!-- {{{stringify properties}}} -->

Accessing layout properties

You can access the values of properties defined in your configuration file using the properties object in your Handlebars template.

<div class="layout {{#if properties.showSidebar}}has-sidebar{{/if}}">
  <h1>{{properties.customHeading}}</h1>
  ...
</div>

CSS integration

The CSS classes used in the template must be part of your website design or manually included for local testing.

Website Design (Live): When deployed, your layout has access to the CSS provided by the website design. The classes you use in your template should match those defined in your system’s CSS framework or custom stylesheets.
Manual Integration (Local): To test locally, you must manually load the required CSS using the --stylesheet flag in the CLI. This ensures that the layout renders correctly in your local browser even without access to the live system’s design assets.

The layout examples in this documentation use Bootstrap-based utility classes for sizing and alignment, for example, d-flex and w-25.

Help Center

Menu