Custom layout: Advanced functionality explained

Defining custom variables

Custom variables make your layouts more flexible by letting site owners configure behavior in the property panel without editing code. They’re defined in the <variables> section of your metadata and accessed in your layout with Handlebars.

Supported types

• string: Text input (e.g. headings, labels)
• number: Numeric values (e.g. opacity, item count)
• boolean: True/false toggles (e.g. show/hide)
• choice: Dropdown list of options (e.g. theme, style)

Defining variables

Add a <variable> tag inside <variables> in your metadata:

<template id="metadata" data-name="Customizable Layout">
  <variables>
    <variable feature="content" name="sectionTitle" type="string"
              label="Section title" default="Latest News" />
    <variable feature="content" name="showIcons" type="boolean"
              label="Show icons" default="true" />
    <variable feature="content" kind="slider" name="opacity" type="number"
              default="50" min="0" max="100" label="Overlay opacity" />
    <variable feature="content" name="theme" type="choice"
              label="Theme" default="blue">
      <choice value="blue" label="Blue" />
      <choice value="green" label="Green" />
      <choice value="red" label="Red" />
    </variable>
  </variables>
</template>

Variable attributes

• feature: Feature this variable belongs to (content, greeting, background, etc.)
• name: Variable name (letters only, no spaces)
• type: One of: string, number, boolean, choice
• label: Friendly name shown in the property panel
• default: Default value

Optional: scope (global/slide), min/max (numbers), showWhen (conditional display).

Scope

• Global (default): applies to the entire feature.
• Slide: applies to individual slides when used with the content feature.

<variable feature="content" scope="slide" name="backgroundColor" type="choice"
         label="Slide background color" default="white">
  <choice value="white" label="White" />
  <choice value="dark" label="Dark" />
</variable>

Using variables in layouts

Reference values using Handlebars:

<h2>{{custom.content.sectionTitle}}</h2>

{{#if custom.content.showIcons}}
  <div class="icons">...</div>
{{/if}}

<div style="opacity: {{custom.content.opacity}}%">
  <!-- content -->
</div>

Best practices

• Use descriptive names
• Provide sensible defaults
• Write clear labels for end users
• Group related variables under the same feature
• Test different combinations

Localization

You can add labels in multiple languages:

<variable feature="content" name="cycle" type="boolean" default="false"
         label="Auto-cycle content"
         label-fr-fr="Faire défiler automatiquement le contenu"
         label-de-de="Inhalt automatisch durchlaufen"
         label-es-es="Ciclar contenido automáticamente" />

{{#audience "00000000-0000-0000-0000-000000000000"}}
    <div>Content for audience 1</div>
{{else}}
    {{#audience "11111111-1111-1111-1111-111111111111"}}
        <div>Content for audience 2</div>
    {{else}}
        <div>Default content</div>
    {{/audience}}
{{/audience}}

{{#audience custom.content.secret}}
    <div>This content is only visible to the specified audience</div>
{{/audience}}

function onInitialize() {
    console.log('Layout initialized');
    // Set up resources, event listeners, etc.
    
    var webPart = ctx.getWebPart(); // get web part context
    
    // Example: Make a SharePoint REST API call
    webPart.spHttpClient.get(
        webPart.pageContext.web.absoluteUrl + '/_api/web?$select=Title', 
        webPart.spHttpClient.constructor.configurations.v1, 
        { headers: { 'Accept': 'application/json' } }
    )
    .then(function(response) {
        return response.json();
    })
    .then(function(data) {
        console.log('Web Title:', data.Title);
    })
    .catch(function(error) {
        console.error('Error:', error);
    });
}

function onError(error) {
    console.error('Layout error:', error);
    // Handle errors
}

function onDispose() {
    console.log('Layout disposed');
    // Clean up resources, remove event listeners, etc.
    clearInterval(interval); // example: clean up interval
}

// Get a custom variable value
var hideTime = ctx.getVariable('custom.time.hide');

// Access the web part context
var webPart = ctx.getWebPart();

// Make SharePoint API calls
webPart.spHttpClient.get(
    webPart.pageContext.web.absoluteUrl + '/_api/web', 
    webPart.spHttpClient.constructor.configurations.v1, 
    { headers: { 'Accept': 'application/json' } }
)
.then(response => response.json())
.then(data => console.log('Web Title:', data.Title))
.catch(error => console.error('Error:', error));