Custom layout: Advanced functionality explained

Basic structure:

<settings>
    <content>
        <fields>
            <field name="FieldName1" />
            <field name="FieldName2" />
        </fields>
    </content>
</settings>

Example:

<settings>
    <content>
        <fields>
            <field name="ShowInWelcome" />
            <field name="Category" />
            <field name="Priority" />
        </fields>
    </content>
</settings>

{{#each content}}
    {{#if custom.ShowInWelcome}}
        <div class="item">
            <h3>{{title}}</h3>
            {{#if custom.Category}}
                <span class="category">Category: {{custom.Category}}</span>
            {{/if}}
            {{#if custom.Priority}}
                <span class="priority priority-{{custom.Priority}}">{{custom.Priority}}</span>
            {{/if}}
        </div>
    {{/if}}
{{/each}}

Common use cases

Advanced example

{{#each content}}
    {{#if custom.ShowInWelcome}}
        <div class="card {{#if custom.IsHighlighted}}highlighted{{/if}}">
            <h3>{{title}}</h3>
            
            {{#if custom.Categories}}
                <div class="categories">
                    {{#each custom.Categories}}
                        <span class="tag">{{this.label}}</span>
                    {{/each}}
                </div>
            {{/if}}
            
            {{#if custom.Expires}}
                <div class="expires-on">Expires: {{formatDate custom.Expires "MM/DD/YYYY"}}</div>
            {{/if}}
            
            {{#if custom.Owner}}
                <div class="owner">
                    <img src="{{custom.Owner.pictureUrl}}" alt="{{custom.Owner.displayName}}" />
                    <span>{{custom.Owner.displayName}}</span>
                </div>
            {{/if}}
        </div>
    {{/if}}
{{/each}}

Custom variables

The custom variable is organized by feature and contains user-defined settings:

Audience targeting

To specify which audiences to load, you must list them in a settings metadata section:

<settings>
    <content>
        <fields>
            <field name="WelcomeNewsCategory" />
        </fields>
    </content>
    <!--
                    List any audiences ids you want to use in your template. These ids then can be used with {{#audience "<guid>"}} helper.
                -->
    <audiences>
        <audience id="54698842-c8c0-4c95-9832-b88a52065ab3" />
    </audiences>
</settings>

You can conditionally render content based on audience targeting using Handlebars helpers:

{{#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}}

You can also use variables for dynamic audience targeting:

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

Lifecycle hooks

Three JavaScript functions can be defined to hook into the layout's lifecycle:

1. onInitialize()

Called when the layout is initialized

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);
    });
}

2. onError(error)

Called when an error occurs

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

3. onDispose()

Called when the layout is disposed

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

JavaScript context

A global ctx object is available in your scripts to interact with the Welcome app:

// 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));

Understanding the .SCOPE pseudo-class

The .SCOPE pseudo-class is a special selector in Welcome app layouts that gets replaced at runtime with the actual scope of the web part instance (e.g., #acc365-Welcome-12345). This provides several benefits:

• CSS Isolation: Ensures your styles don't affect other elements on the page
• CSS Variables: Define CSS variables that are scoped only to your web part
• External Targeting: Safely target elements outside your layout when necessary
• Prevent Collisions: Avoid CSS class name collisions with other components

When the layout is rendered, .SCOPE is replaced with the actual web part container selector, turning:

.SCOPE { --primary-color: #0078d4; }

into something like:

#acc365-Welcome-12345 { --primary-color: #0078d4; }

This allows you to safely define styles that won't interfere with other elements on the page, even if they use the same class names.

⬅️Back: Custom layout: Core functionality explained