FIGURE 8-4 The Help

FIGURE 8-4 The Help settings flyout (truncated vertically) from Scenario 2 of the App settings sample. Notice the hyperlink on the lower right. In any case, you can see that everything within the control is just markup for the flyout contents, nothing more, and you can wire up events to controls in the markup or in code. You’re free to use hyperlinks here, such as to launch the browser to open a fuller Help page. You can also use an iframe to directly host web content within a settings flyout, as demonstrated in Scenario 3 of the same sample. So how do we get this flyout to show when a command is invoked on the top-level settings pane? The easy way is to let WinJS take care of the details using the information you provide to WinJS.UI.- SettingsFlyout.populateSettings. Here’s the example again from Scenario 2, as we saw in the previous section: WinJS.Application.onsettings = function (e) { e.detail.applicationcommands = { "help": { title: "Help", href: "/html/2-SettingsFlyout-Help.html" } }; WinJS.UI.SettingsFlyout.populateSettings(e); }; In the JSON you assign to applicationCommands, each object identifies both a command and its associated flyout. The name of the object is the flyout id (“help”), its title property provides the command label for the top-level settings pane (“Help” in the above), and its href property identifies the HTML page where the flyout with that id is declared (“/html/2-SettingsFlyout-Help.html”). With this information, WinJS can both populate the top-level settings pane and provide automatic invocation of the desired flyout (calling WinJS.UI.process all along the way) without you having to write any other code. This is why in most of the scenarios of the sample you don’t see any explicit calls to showSettings, just a call to populateSettings. 340

Programmatically Invoking Settings Flyouts Let’s now see what’s going on under the covers. In addition to being a control that you use to define a specific flyout, WinJS.UI.SettingsFlyout has a couple of other static methods besides populateSettings: show and showSettings. The show method specifically brings out the top-level Windows settings pane—that is, Windows.UI.ApplicationSettings.SettingsPane. This is why you see the back button’s click event in the above markup wired directly to show, because the back button should return to that top-level UI. Note While it’s possible to programmatically invoke your own settings panes, you cannot do so with system-provided commands like Permissions and Rate and Review. If you have a condition for which you need the user to change a permission, such as enabling geolocation, the recommendation is to display an error message that instructs the user to do so. The showSettings method, on the other hand, shows a specific settings flyout that you define somewhere in your app. The signature of the method is showSettings( [, ]) where identifies the flyout you’re looking for and the optional parameter identifies an HTML document to look in if a flyout with isn’t found in the current document. That is, showSettings will always start by looking in the current document for a WinJS.UI.SettingsFlyout element that has a matching settingsCommandId property or a matching HTML id attribute. If such a flyout is found, that UI is shown. If the markup in the previous section (with Figure 8-4) was contained in the same HTML page that’s currently loaded in the app, the following line of code will show that flyout: WinJS.UI.SettingsFlyout.showSettings("help"); In this case you could also omit the href part of the JSON object passed to populateCommands, but only again if the flyout is contained within the current HTML document already. The parameter, for its part, allows you to separate your settings flyouts from the rest of your markup; its value is a relative URI within your app package. The App settings sample uses this to place the flyout for each scenario into a separate HTML file. You can also place all your flyouts in one HTML file, so long as they have unique ids. Either way, if you provide a , showSettings will load that HTML into the current page using WinJS.UI.Pages.load (which calls WinJS.UI.processAll), scans that DOM tree for a matching flyout with the given , and shows it. Failure to locate the flyout will cause an exception. Scenario 5 of the sample shows this form of programmatic invocation. This is also a good example (see Figure 8-5) of a vertically scrolling flyout: WinJS.UI.SettingsFlyout.showSettings("defaults", "/html/5-SettingsFlyout-Settings.html"); 341