Quickstart: add app help (HTML)

Article
08/31/2015

This quickstart shows you how to add a Help flyout to the Settings pane using HTML and the SettingsFlyout object for the Windows Library for JavaScript (WinJS). To see a Help flyout in a complete app, see the App settings sample.

In the following example, you'll define a Settings flyout, called Help, in an HTML file (HelpUI.html). You'll then initialize the Settings flyout and populate the Settings pane using JavaScript.

Using C#/Visual Basic/C++ and XAML? See Quickstart: Add app help (Windows Store apps using C++, C#, or VB and XAML).

Prerequisites

Read the Guidelines for app help and the Guidelines for app settings.

Instructions

Create an HTML file named "HelpUI.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 data-win-options="{settingsCommandId:'helpDiv', width:'wide'}" to create 
         a wide flyout. -->
    <!-- Set the background color for the header to the background color defined
         for your app tile in the manifest. -->
    <div data-win-control="WinJS.UI.SettingsFlyout"
         data-win-options="{settingsCommandId:'helpDiv', width:'wide'}">
        <div class="win-ui-dark win-header" title="Help">
            <button type="button" 
                    onclick="WinJS.UI.SettingsFlyout.show()"
                    class="win-backbutton"></button>
            <div class="win-label">Help</div>
        </div>
        <div class="win-content">
            <!-- Help content here -->
        </div>
    </div>
    <!-- ENDTEMPLATE -->
</body>
</html>

Note By default, this flyout will be "narrow" (346px) in width. Set data-win-options="{settingsCommandId:'helpDiv', width:'wide'}" to create a wide flyout (646px).

The following code processes the Settings flyout and populates the SettingsPane using JavaScript. Call this function when activating your app.

function initializeSettings() {
    // Initialize Settings flyout(s) and WinJS controls.
    WinJS.UI.processAll();
    
    // Populate Settings pane and tie commands to Settings flyouts.
    WinJS.Application.onsettings = function (e) {
        e.detail.applicationcommands = {
            "helpDiv": { href: "HelpUI.html", title: "Help"}
        };
        WinJS.UI.SettingsFlyout.populateSettings(e);
    }
    WinJS.Application.start();
}

Note This function should be called after your DOM has initialized. But don't worry about DOM initialization if you're calling initializeSettings from the onactivated function; the activated event occurs after the DOMContentLoaded event. For more info, see Optimizing your app's lifecycle (Windows Store apps using JavaScript and HTML).