Quickstart: Adding app settings using Windows Library for JavaScript

  • Article

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

See this feature in action as part of our App features, start to finish series: Windows Store app UI, start to finish

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. Create a blank app

Create a "Hello World" blank app as described in Create a "Hello, world" app. You need to complete only the first two steps:

  1. Create a new project in Visual Studio.
  2. Launch the app.

2. Define the Default settings flyout

Still in Visual Studio, create an HTML file named DefaultSettings.html:

  1. In the Solution Explorer pane, under the "HelloWorld" solution, right-click the project HelloWorld.
  2. Select Add, New Folder.
  3. Name the new folder "html".
  4. Right-click on the folder and select Add, New HTML File....
  5. Select HTML Page, enter the name "DefaultSettings.html", and click Add.

Copy the following, and paste it over the contents of the new file.


<!doctype HTML>
<html>
    <head>
        <title>App defaults 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' (346px) or 'wide' (646px). -->
        <!-- 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="{settingsCommandId:'help',width:'narrow'}">
            <div class="win-header" style="background-color:#464646">
                <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"></button>
                <div class="win-label">Defaults</div>
                <img src="ms-appx:///images/smalllogo.png" style="position: absolute; right: 40px;" />
            </div>
            <div class="win-content">
                {App defaults content goes here}
            </div>
        </div>
        <!-- ENDTEMPLATE -->
    </body>
</html>

3. Define the Help flyout

Create an additional HTML file named HelpUI.html under the "html" folder.

Copy the following, and paste it over the contents of the new file.

<!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' (346px) or 'wide' (646px). -->
        <!-- 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="{settingsCommandId:'help',width:'narrow'}">
            <div class="win-header" style="background-color:#464646">
                <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"></button>
                <div class="win-label">Help</div>
                <img src="ms-appx:///images/smalllogo.png" style="position: absolute; right: 40px;" />
            </div>
            <div class="win-content">
                {Help content goes here}
            </div>
        </div>
        <!-- ENDTEMPLATE -->
    </body>
</html>

4. Populate the Settings pane

Process the Settings flyout and populate the Settings pane by adding the following JavaScript to default.js. Place the new code within the onactivated function so that it will be run after your DOM has initialized.


    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll());

            // BEGIN BLOCK OF NEW CODE
            // Populate Settings pane and tie commands to Settings flyouts.
            WinJS.Application.onsettings = function (e) {
                e.detail.applicationcommands = {
                    "defaultsDiv": { href: "html/DefaultSettings.html", title: "App defaults" },
                    "helpDiv": { href: "html/HelpUI.html", title: "Help" }
                };
                WinJS.UI.SettingsFlyout.populateSettings(e);
            }
            // END OF BLOCK

        }
    };

Summary

In this quickstart, you learned to set up the Settings contract by using HTML and the WinJS.

Samples

Application settings sample

Reference

SettingsFlyout

Docs

Quickstart: Using Windows Runtime

Guidelines for app settings