Custom layout: Core functionality (Welcome)

If you’ve already created your first custom layout using our getting started guide, this article takes you one step further. Here, we break down the core building blocks of the Welcome app’s custom layout system, covering available variables, feature flags, templating syntax, and how to use widgets and components effectively.

Use this guide as your go-to reference when shaping more polished, feature-rich layouts.

Jump to

• Handlebars templating
• Variables
• Conditional visibility
• Features
  
• Widgets and components
• Best practices

Handlebars templating

The Welcome app uses Handlebars as its templating engine. This allows you to:

1. Insert variable values: {{variable}}

    

2. Insert unescaped HTML: {{{variable}}}
3. Use conditional logic: {{#if variable}}...{{else}}...{{/if}}
4. Loop through arrays: {{#each array}}...{{/each}}
5. Use custom helpers like audience targeting: {{#audience "guid"...{{/audience}}

<!-- Display the username -->
<h1>Hello, {{username}}!</h1>

<!-- Insert an unescaped background URL -->
<div style="background-image: url({{{background}}})"></div>

<!-- Conditional rendering -->
{{#unless custom.greeting.hide}}
    <div class="greeting">
        <a365widget data-widget="greeting"></a365widget>
    </div>
{{/unless}}

<!-- Loop through content items -->
{{#each content}}
    <div class="item">
        <h2>{{title}}</h2>
        <p>{{description}}</p>
    </div>
{{/each}}

Variables

The following variables are available for use in your Handlebars templates.

The content variable is an array of Slide objects with the following properties:

Conditional visibility

Any <variable> - a custom variable you define, or a built-in override of an existing field - can be shown or hidden depending on the current value of another feature setting. This lets you build layouts where one option appears only when a related option is set in a certain way.

Add a showWhen attribute to the <variable> tag:

<variable feature="content" name="cycleSeconds" type="number"
    label="Seconds between slide changes"
    showWhen="content.cycle" />

Syntax

You can reference:

• Another custom variable, e.g. content.myOtherVariable==foo
• A built-in/OOTB value, e.g. time.timeDisplay==custom, content.kind==video
• Values can be chained - variable B's showWhen can depend on variable A, which itself has its own showWhen.

Examples

<variable feature="time" name="acc-timeDisplayDate"
    showWhen="time.timeDisplay==custom" />

<variable feature="content" scope="slide" name="acc-slideOverlay"
    showWhen="content.kind==video" />

The first field only appears once the Time feature's display mode is set to "Custom." The second only appears on slides of type "video."

Features

Features are enabled via data attributes on the metadata template. Each feature adds specific functionality to your layout:

Widgets and components

Widgets are high-level UI elements that combine multiple components:

<a365widget data-widget="greeting"></a365widget>
<a365widget data-widget="time"></a365widget>
<a365widget data-widget="weather"></a365widget>
<a365widget data-widget="search"></a365widget>
<a365widget data-widget="content"></a365widget>

Components are lower-level UI elements that can be used independently:

<a365component data-component="greeting"></a365component>
<a365component data-component="photo"></a365component>
<a365component data-component="time"></a365component>