Custom layout: Advanced functionality - Custom variables & overrides (Welcome)

Custom variables

Custom variables let you define configurable settings for your layouts. They are grouped by feature, and you can access them in your templates like this:

Declaring a custom variable

To add a custom variable, declare it inside a <variables> block within your metadata template:

<template id="metadata" data-name="My layout" data-feature-content="true"...>
    <variables>
        <variable feature="content" name="cycleSeconds" type="number"
            label="Seconds between slide changes"
            default="5" />
    </variables>
</template>

This adds a field labeled "Seconds between slide changes" to the Content section of the Manage panel. Once set by the content editor, its value is available in your template at custom.content.cycleSeconds, and in JavaScript via ctx.getVariable('custom.content.cycleSeconds').

Every custom variable needs a type, which determines what kind of input renders in the Manage panel - see the full type-specific attribute tables further down.

Common attributes

Every <variable> supports these attributes regardless of type:

Type-specific attributes 

type="string"

type="richtext" (rich text editor)

Rich text always ignores the section's inherited theme color when rendering (fixed, not configurable). Empty content renders nothing rather than an empty block.

type="color"

type="list" (options sourced from a SharePoint list)

Built-in overrides

Every feature (Greeting, Time, Weather, Search, Content/Slides, Background) already has its own built-in fields in the Manage panel - slide title, subtitle, overlay color, schedule, audience, and so on. A layout author can reference these existing fields by name to hide them, relabel them, reorder them, or make them conditional - without redefining the field itself.

To do this, add a <variable> whose name matches the built-in field's identifier (always prefixed acc-), inside the <variables> block of your metadata template:

<variable feature="content" name="acc-slideOverlay"
    label="Overlay color"
    hidden="false"
    order="6"
    showWhen="content.featuredImage" />

Supported attributes on a built-in override:

Example - layout-specific brand palette on the slide overlay picker, only shown once a featured image is set:

<variable feature="content" name="acc-slideOverlay" label="Overlay color"
    morecolors="true" brandcentercolors="true" defaultcolor="#000000" hidestandardcolors="true"
    order="6" showWhen="content.featuredImage">
    <color key="#000000" title="Black" />
    <color key="#ffffff" title="White" />
</variable>

 Full list of overridable built-in fields

Not every override supports every attribute - the "Overridable via" column lists exactly which of hidden / showWhen / order / label (+ color-specific attributes) each field actually respects. Setting an unsupported attribute is silently ignored.

 Feature/slide-scoped overrides (Content/Slides) need scope="slide" on the <variable> tag, same as slide-level custom variables.

Video slides

Content slides can be of type video (source: YouTube, Vimeo, OneDrive, SharePoint, or direct upload), configured entirely by the content editor in the Manage panel - there is no <variable type="video"> to declare.

Step 1 - opt in. Video slides only appear as an option in the Manage panel if the layout's metadata declares support for them:

<template id="metadata" data-name="My layout" ... data-supports-video="true">

Without data-supports-video="true", editors cannot add a video slide at all, and any existing video slides are skipped when rendering (they never appear on the front end).

Step 2 - render it. Simply add this component to your slide markup:

<div data-component="carousel-slide-video" src="{{embedUrl}}" background="{{background}}"
    id="{{id}}" loop="{{loop}}" muted="{{muted}}" alt="{{altText}}"></div>

The full slide markup looks like the existing built-in "Featured" layout example (src/app/Welcome/shared/assets/layouts/featured.layout.html):

<div data-component="carousel-slide" id="{{id}}" class="featured__slide featured__slide--{{overlayColor}}">
    <div data-component="hide-when" slideid="{{id}}" property="playingId">
        <div data-component="carousel-slide-gradient" color="{{overlayColor}}" opacity="{{overlayOpacity}}"></div>
        <!-- title / subtitle / greeting / time / weather markup here -->
        <div data-component="carousel-slide-image" src="{{background}}" alt="{{altText}}"
            {{#if (eq kind "video")}}showdefault="false"{{/if}}></div>
        <div data-component="carousel-text" title="{{title}}" subtitle="{{subtitle}}" url="{{ctaUrl}}" text="{{ctaText}}"></div>
        <div data-component="slide-toolbar" id="{{id}}"></div>
    </div>
    <div data-component="carousel-slide-video" src="{{embedUrl}}" background="{{background}}"
        id="{{id}}" loop="{{loop}}" muted="{{muted}}" alt="{{altText}}"></div>
</div>

Use showWhen="content.kind==video" to show a field only on video slides, e.g.:

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

➡️ Next: Custom layout: Advanced integration - Data, audience & lifecycle

⬅️ Back: Custom layout: Core functionality