Navigation model

  • Article

The navigation model used in the Grid, Split, and Navigation App project templates is the recommended navigation model for multi-page Windows Store apps built for Windows using JavaScript. In this model, logical HTML pages, loaded via the page's URI, get loaded into a single app-wide context. The logical pages are loaded into the app context as needed, typically in response to user actions. Web developers often refer to this type of navigation model as single-page navigation. The navigator.js file implements the navigation model. The single-page navigation model provides a smoother, app-like transition between pages, and also makes it easier to manage state, because scripts are never unloaded.

Other project templates such as the Blank template do not include a navigator.js file. For this template, you will need to implement custom navigation if you do not add the navigator.js project file manually. If you use the WinJS.Navigation.navigate to navigate between pages, keep in mind that WinJS.Navigation.navigate does not perform navigation directly, but this function is a wrapper function that stores a state object associated with your current location, and then invokes the WinJS.Navigation.onnavigated event. For more info on navigation and an example of using single-page navigation in Windows Store apps built for Windows using JavaScript, see QuickStart: using single page navigation.

For help choosing the best navigation pattern for your app, see Navigation patterns. Also, see the Flat navigation pattern in action as part of our App features, start to finish series.

In the single-page navigation model used in the Grid, Split, and Navigation App templates, a DIV element that's declared as the app's navigation control (in default.html) provides the content host for all the app's pages. The DIV element uses the Windows Library for JavaScript data-win-control attribute to declare itself as the navigation control, and this control provides the navigation model for the app. All page content is loaded into this DIV. The element, shown here, is included in default.html in the Split template.

<div id="contenthost" data-win-control="Application.PageControlNavigator"
    data-win-options="{home: '/pages/items/items.html'}">
</div>

The navigation control, PageControlNavigator, shown here, defines several functions that are used for navigation. This control is implemented in navigator.js.

WinJS.Namespace.define("Application", {
    PageControlNavigator: WinJS.Class.define(
        // Define the constructor function for the PageControlNavigator.
        function PageControlNavigator(element, options) {
            // Initialization code.
            }, {
                // Members specified here.
            }
    ), // . . .
});

The constructor function performs initialization for the navigation control. A few important tasks include setting handlers for WinJS events, such as the WinJS.Navigation.onnavigating event, and setting the home page of the app. (The home value is specified in the contenthost DIV element, in a data-win-options attribute.)

// Initialization code.
this.home = options.home;
// . . .
// The 'nav' variable is set to WinJS.Navigation.
addRemovableEventListener(nav, 'navigating', this._navigating.bind(this), false);
addRemovableEventListener(nav, 'navigated', this._navigated.bind(this), false);

The pages loaded into the content host are page controls, which are defined in the WinJS.UI.Pages namespace. A page control is a modular unit of HTML, CSS, and JavaScript that functions as a logical page. When you use page controls, there's a set of predefined methods that the library calls automatically, in a predefined order. The WinJS.UI.Pages.define function exposes these methods for implementation. Here's a portion of the define function in split.js (the Split App template).

WinJS.UI.Pages.define("/pages/split/split.html", {
    // . . .
    ready: function (element, options) {
        // ready function implementation.
    },
    // . . .
});

The project templates implement the last of the internal page control methods—the ready function and, for some templates, the init function. (The other functions defined in split.js are template-specific.) The ready function is called when the page is loaded and fully processed. This function should contain the initialization code for each page. The code is unique for each page.

Tip  The internal page control functions are called in this order: load, init, processed, and ready. Typically, only the ready and init functions are implemented in a Windows Store app. For more info, see IPageControlMembers.init.

To navigate to a new page, each template app calls WinJS.Navigation.navigate. These calls cause the navigation control to load the HTML file as a logical page into the content host DIV element. Several functions in the template pages call the WinJSnavigate function:

  • The _itemInvoked function, which handles the selection of an item in a list view. Depending on the current page and context, the selection might be in individual item or a group.
  • The _selectionChanged function, which handles the selection of an item in split.html (in the Split template).

In some templates, particular functions in the JavaScript files of the HTML pages might modify the Back button history, depending on the current view state. For example, in the Split App template, the app modifies the Back button history if the app is in a template-defined view state called a master/detail view. For more info, see the "Handling view state" section in JavaScript project templates for Windows Store apps.

JavaScript project templates for Windows Store apps

JavaScript item templates for Windows Store apps

 

 

Send comments about this topic to Microsoft

Build date: 11/8/2013