Custom layout: Getting started

With custom layouts, you can completely tailor the look and feel of the Welcome app from layout structure and colours to the content itself.

This guide walks you through the essentials to get up and running with your own custom layout. It’s aimed at developers or those comfortable with HTML and CSS.

1. How it works

A custom layout is just two <template> blocks in one HTML file:

• Metadata (<template id="metadata">):
  Defines your layout’s name, description, and which features are on or off (greeting, time, weather, etc.).

• Layout (<template id="layout">):
  Contains your HTML, CSS, and any widget tags (<a365widget>), plus inline Handlebars syntax ({{username}}, loops, conditionals).

Welcome merges your metadata and layout code to render your custom design.

2. Example custom layout

Below is a simple example of a complete custom layout.

<template id="metadata" data-name="Simple Layout" data-description="A simple layout example"
    data-author="Your Name" data-feature-greeting="true" data-feature-time="true">

    <template id="layout">
        <style>
            .layout {
                padding: 32px;
                background-color: #F8E9E5;
                border-radius: 8px;
                text-align: center;
    display: flex;
    justify-content: center;
                flex-direction: column;
            }

            .greeting {
                font-size: 32px;
                margin-bottom: 16px;
    display: flex;
    justify-content: center;
            }
   
            .greeting .a365-greeting__photo {
                width: 100px;
                height: 100px;
                border-radius: 50%;
                margin-bottom: 16px;
            }  

   .greeting .a365-greeting__message {
                font-size: var(--fontSizeHero700, 28px);
            }

            .time {
                font-size: 32px;
                color: #555;
    display: flex;
    justify-content: center;    
            }
   
   .time .a365-time {
    display: flex;
    justify-content: center;
   }
   
   .time .a365-time > div {
    display: flex;    
   }   
   
   .time .a365-time__date {
    font-family: var(--fontFamilyCustomFont200, var(--fontFamilyBase, inherit));
    font-size: var(--fontSizeBase500, 20px);   
   }

        </style>

        <section class="layout">
            <div class="greeting">
                <a365widget data-widget="greeting"></a365widget>
            </div>
            <div class="time">
                <a365widget data-widget="time"></a365widget>
            </div>
        </section>
    </template>
</template>

Result:

1. Copy the example and save it as an HTML file.
2. Navigate to your SharePoint site with the Welcome app. Provided a data source has been created in the app, a document library will be available in Site Contents, called 'Welcome Web Part - Custom Layouts'.
3. Upload the HTML file to the document library.
4. Edit the Welcome app. The custom layout will be available for selection.

3. Next steps

Once you’ve got the example custom layout working, you can:

1. Turn on extra features
   Add data-feature-time="true", data-feature-weather="true", etc., to your metadata.

2. Insert variables
   Use {{username}}, {{background}}, or loop through {{#each content}}…{{/each}}.

3. Scale up your design
   Copy/paste your favourite CSS framework or branding styles into the <style> block.

➡️Next: Custom layout: Core functionality explained