How to commit settings instantly

For Windows Store apps, all settings are applied as soon as the user changes their values. This model is important because the user can walks you through instantly committing settings using the WinJS Settings flyout and local application data.

Prerequisites

Read the Guidelines for app settings.

Add a Settings flyout to the Settings charm

For more details on how to add a Settings flyout, refer to Quickstart: Adding app settings using Windows Library for JavaScript. But here is a summary.

Define the HTML for your Settings flyout:

<div aria-label="App Settings Flyout" data-win-control="WinJS.UI.SettingsFlyout" data-win-options="{settingsCommandId:'settingsExample', width:'narrow'}">
<!-- Add the background color matching you app tile color to the Settings flyout header. -->
<!-- Use add the win-ui-dark class if the background color requires a white text  -->
<!-- Add the app small logo to the Settings flyout header                         -->
    <div class="win-header win-ui-light" style="background-color: #dbf9ff;">
        <button class="win-backbutton" onclick="WinJS.UI.SettingsFlyout.show()" type="button"></button>
     <div class="win-label">Example</div>
     <img alt="smalllogo" src="/images/smalllogo.png" style="height: 30px; width: 30px; position: absolute; right: 40px;"/>
    </div>
    <div class="win-content">
    <!—Your settings contents go here -->
    </div>
</div>

Attach your Settings flyout to Settings charm:

WinJS.Application.onsettings = function (e) {
    e.detail.applicationcommands = {
        "settingsExample": { title: "Example" }
    };
    WinJS.UI.SettingsFlyout.populateSettings(e);
};

Add controls to the Flyout

In this example we are adding a toggle control and a select control to our Settings flyout. These are two of the most common controls for settings.

<div class="win-content">
    <div class="win-settings-section">
        <h3>Example settings section</h3>
        <p>Description: toggle and select are common settings controls</p>
        <div id="settingsToggle" data-win-control="WinJS.UI.ToggleSwitch" 
             data-win-options="{title:'Example toggle switch', 
             onchange: settingsToggleChange}"></div>
    </div>
    <div class="win-settings-section">
        <h3>Select control</h3>
        <p>Select controls let users select an item from a set of text only items.</p>
        <label>Example select control</label>
        <select id="settingsSelect" aria-label="Example select control">
            <option value="1">Value 1</option>
            <option value="2">Value 2</option>
            <option value="3">Value 3</option>
            <option value="4">Value 4</option>
        </select>
    </div>
</div>

Note  

• We added an onchange event option to the data-win-options for the settingsToggle. This registers the onchange event for the ToggleSwitch control. For more details see Guidelines for toggle switches.
• The settings are wrapped in win-settings-section CSS classes and use the recommended elements to achieve styling aligned with the settings guidelines (see Guidelines for app settings).

Initialize the controls from the local app data store

In this example we are using the local Application data store. Every time the Settings flyout is invoked by the user we will read the values from the application data to ensure the controls in the UI reflect the latest values.

function initSettingsControls() {
    // Initialize the toggle control using the current value of settingsToggleValue in the local state store
    var toggleControl = document.getElementById("settingsToggle").winControl;
    toggleControl.checked = (Windows.Storage.ApplicationData.current.localSettings.values["settingsToggleValue"] === "on");

    // Initialize the select control using the current value of settingsSelectValue in the locale state store
    var selectControl = document.getElementById("settingsSelect");
    var settingsSelectValue = Windows.Storage.ApplicationData.current.localSettings.values["settingsSelectValue"];
    for (var i = 0; i < selectControl.options.length; i++) {
        if (selectControl.options(i).value === settingsSelectValue) {
            selectControl.selectedIndex = i;
            break;
        }
    }

    // Add event listener for change event on select control
    selectControl.addEventListener("change", settingsSelectChange, false);
}

Note  

• Ensure that initialization of controls happens after the DOM has loaded and the WinJS controls have been initialized. When using a Settings flyout defined in its own HTML page this may require a call the pages control ready method to make sure the Settings flyout is ready to use.
• Note that in this example we use the local application data store. You could use the roaming application data store to ensure the settings are roamed automatically. Refer to Guidelines for roaming application data for more details.

Handle change events to Settings controls

This is where instant commit really happens. When the user changes the values associated with the control we immediately write the new value to the application data store. This is done in the onchange event handler associated with the control.

function settingsToggleChange() {
    var toggleControl = document.getElementById("settingsToggle").winControl;
    // Write new value to the local state store
    Windows.Storage.ApplicationData.current.localSettings.values["settingsToggleValue"] = (toggleControl.checked ? "on" : "off");
}

// To protect against untrusted code execution, all functions are required 
// to be marked as supported for processing before they can be used inside 
// a data-win-options attribute in HTML markup.
WinJS.Utilities.markSupportedForProcessing(settingsToggleChange);

function settingsSelectChange(changedEvent) {
    // Write new value to the local state store
    Windows.Storage.ApplicationData.current.localSettings.values["settingsSelectValue"] = changedEvent.target.options.value;
}

Summary

In this quickstart, you learned how to commit updates to settings instantly.