Share via


Quickstart: add app help (HTML)

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

1. Define the Help flyout.

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).

 

2. Process the Settings flyout and populate the Settings pane.

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).

 

Summary and next steps

In this quickstart, you learned to add app help to the Settings pane by using HTML and the Windows Library for JavaScript.

Next, you can learn to include online help in your help page using iframes.

How to include online content in your help

App settings sample

Quickstart: Adding app settings

WinJS.UI.SettingsFlyout

Windows.UI.ApplicationSettings.SettingsPane

Guidelines for app help

Guidelines for app settings

Quickstart: Add app help (Windows Store apps using C++, C#, or VB and XAML)

Optimizing your app's lifecycle (Windows Store apps using JavaScript and HTML)