Quickstart: Adding app settings using Windows Library for JavaScript (Windows)

Language: JavaScript and HTML | VB/C#/C++ and XAML

2 out of 21 rated this helpful - Rate this topic

This Quickstart walks you through implementing the Settings contract by using HTML and the SettingsFlyout class for the Windows Library for JavaScript.

Introduction

In the following example you will define two settings Flyouts, Defaults and Help, in two separate HTML files. You will process the settings Flyouts and populate the settings pane using JavaScript.

Prerequisites

Read the Guidelines for app settings.

1. Define the Default Flyout

Create an HTML file named Default.html.

HTML


<!doctype HTML>
<html>
    <head>
        <title>Default settings flyout</title>
    </head>
    <body>
        <!-- BEGINTEMPLATE: Template code for an empty Settings Flyout. -->
        <!-- Each settings flyout should be defined in its own HTML file. -->
        <!-- Set the width to 'narrow' for a narrow settings flyout. -->
        <!-- Set the background color for the header to the background color defined for your
             app tile in the manifest. -->
        <div id="defaultsDiv" data-win-control="WinJS.UI.SettingsFlyout" aria-label="App defaults settings flyout"
                data-win-options="{width:'wide'}">
            <div class="win-header" style="background-color:#dbf9ff">
                <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"></button>
                <div class="win-label">Defaults</div>
                <img src="images/smallTile.png" style="position: absolute; right: 40px;"/>
            </div>
            <div class="win-content">
                {Defaults content here}
            </div>
        </div>
        <!-- ENDTEMPLATE -->
    </body>
</html>

2. Define the Help Flyout

Create an HTML file named HelpUI.html.

HTML


<!doctype HTML>
<html>
    <head>
        <title>Help settings flyout</title>
    </head>
    <body>
        <!-- BEGINTEMPLATE: Template code for an empty Help Flyout. -->
        <!-- Each settings flyout should be defined in its own HTML file. -->
        <!-- Set the width to 'narrow' for a narrow settings flyout. -->
        <!-- Set the background color for the header to the background color defined for your
             app tile in the manifest. -->
        <div id="helpDiv" data-win-control="WinJS.UI.SettingsFlyout" aria-label="Help settings flyout"
                data-win-options="{width:'wide'}">
            <div class="win-header" style="background-color:#dbf9ff">
                <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"></button>
                <div class="win-label">Help</div>
                <img src="images/smallTile.png" style="position: absolute; right: 40px;"/>
            </div>
            <div class="win-content">
                {Help content here}
            </div>
        </div>
        <!-- ENDTEMPLATE -->
    </body>
</html>

3. Populate the settings pane

Process the settings Flyout and populate the settings pane by using JavaScript in default.js. This should be done after the DOM has initialized.

JavaScript


 (function () { 
    "use strict"; 
 
    var sampleTitle = "Application Settings"; 
 
    var scenarios = [ 
        { url: "/html/Deafult.html", title: "Default behavior" }, 
        { url: "/html/HelpUI.html", title: "Add Help settings flyout linked to the settings charm" }, 
    ]; 
 
    function activated(eventObject) { 
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) { 
            // Use setPromise to indicate to the system that the splash screen must not be torn down 
            // until after processAll and navigate complete asynchronously. 
            eventObject.setPromise(WinJS.UI.processAll().then(function () { 
                // Navigate to either the first scenario or to the last running scenario 
                // before suspension or termination. 
                var url = WinJS.Application.sessionState.lastUrl || scenarios[0].url; 
                return WinJS.Navigation.navigate(url); 
            })); 
        } 
    } 
 
    WinJS.Navigation.addEventListener("navigated", function (eventObject) { 
        var url = eventObject.detail.location; 
        var host = document.getElementById("contentHost"); 
        // Call unload method on current scenario, if there is one 
        host.winControl && host.winControl.unload && host.winControl.unload(); 
        WinJS.Utilities.empty(host); 
        eventObject.detail.setPromise(WinJS.UI.Pages.render(url, host, eventObject.detail.state).then(function () { 
            WinJS.Application.sessionState.lastUrl = url; 
        })); 
    }); 
 
    WinJS.Namespace.define("SdkSample", { 
        sampleTitle: sampleTitle, 
        scenarios: scenarios 
    }); 
 
    WinJS.Application.addEventListener("activated", activated, false); 
    WinJS.Application.start(); 
})();

4. Optional: Create a settings Flyout that hosts web content.

Suppose you want to create a Legal Notices Flyout that contains web content. First, as you did earlier, you create the HTML Flyout and then you process it in the .js file.

HTML


<!doctype HTML>
<html>
    <head>
       <title>Legal notices settings flyout</title>
    </head>
    <body>
        <!-- BEGINSETTINGSFLYOUT -->
        <div data-win-control="WinJS.UI.SettingsFlyout" aria-label="Legal notices settings flyout" 
             data-win-options="{settingsCommandId:'legalNotices',width:'wide'}">
            <div class="win-ui-dark win-header" style="background-color:#00b2f0"> 
                <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"></button>
                <div class="win-label">Legal notices</div>
                <img src="../images/smallTile-sdk.png" style="position: absolute; right: 40px;"/>
            </div>
            <div class="win-content">
                <div class="win-settings-section">
                    <h3>iFrame support</h3>
                    <div>Use an iFrame to expose dynamic content from a web server.</div>
                    <div id="onlineHelp">
                        <iframe src="http://msdn.microsoft.com/en-us/library/windows/apps/hh770544" 
                                width="566" height="600"/>
                    </div>
                </div>
            </div>
        </div>
        <!-- ENDSETTINGSFLYOUT -->
    </body>
</html>

JavaScript


function initializeSettings() {
    WinJS.Application.onsettings = function (e) {
        e.detail.applicationcommands = { "legalNotices": { title: "Legal notices", 
            href: "LegalNoticesUI.html" } };
        WinJS.UI.SettingsFlyout.populateSettings(e);
    };
    // Make sure the following is called after the DOM has initialized. 
    // Typically this would be part of app initialization
    WinJS.Application.start();
}

Summary

In this quickstart, you learned to set up the Settings contract by using HTML and the Windows Library for JavaScript.

Quickstart: Adding app settings using Windows Library for JavaScript

Prerequisites

1. Define the Default Flyout

2. Define the Help Flyout

3. Populate the settings pane

4. Optional: Create a settings Flyout that hosts web content.

Summary

Related topics