Adding a Page Control item template

Article
11/11/2013

This topic demonstrates how to add the Page Control item template to a Windows Store app that enables you to navigate easily between pages. For descriptions of the item templates, see JavaScript item templates. For most apps, you can use item templates included with Microsoft Visual Studio 2013 to simplify your app development.

The page control item template supports the single-page navigation model that is recommended for multi-page Windows Store apps. The Hub, Grid, Split, and Navigation project templates implement this navigation model. The navigation model provides a single content host page (default.html) and enables navigation among logical pages that are loaded into the content host. For more info, see Navigation model.

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

When you add a new page to a Visual Studio project, you need to:

Add the new page using the Visual Studio Page Control item template.
Add code to navigate to the new page using the WinJS.Navigation.navigate function.

Tip This function does not perform navigation directly, but invokes the WinJS.Navigation.onnavigated event, which is handled in navigator.js. Code in navigator.js calls the ready function in your new page. Typically, you don't need to modify navigator.js.
Add UI and event handlers appropriate to your app, if necessary, to invoke the page navigation code.

Caution To use the Page Control item template with the Blank template, you will need to add navigator.js to the project and also add the content host code to default.html (you can obtain navigator.js and the content host code from another project template, such as Grid). For more info, see Navigation model.

Create the project

First, we'll create an app by using the Navigation template. The Navigation template provides a very simple app in which the multi-page navigation model is already provided.

Tip If you are using the Hub, Grid, or Split template, the steps are similar, but the file names are different. The HTML and CSS code below will need to be modified to fit the template.

Hh920268.wedge(en-us,WIN.10).gif To create the project

In Visual Studio, choose File > New Project.
In the left pane of the New Project dialog box, expand the JavaScript node.
In the center pane, choose Navigation App.
Name the project NavApp and click OK.

The solution is created and the project files appear in Solution Explorer. For more info about the project files, see JavaScript project templates.

Note When you run Visual Studio for the first time, it prompts you to obtain a developer license.
To run the program, choose Debug > Start Debugging, or choose F5. The following page content appears: "Welcome to NavApp!"
Choose SHIFT + F5 to stop debugging and return to Visual Studio.

Add the page control

In this section, we'll add the Page Control item template. After that, we'll add code to navigate among the pages.

Hh920268.wedge(en-us,WIN.10).gif To add the page control

In Solution Explorer, open the shortcut menu for the pages folder and choose Add > New Folder.
Name the new folder page2.
Open the shortcut menu for the page2 folder, and then choose Add > New Item.
In the Add New Item dialog box, choose Page Control in the middle pane.
Name the page page2.html and choose Add.

The page2.html file is created in the page2 folder, along with two other project files: page2.css and page2.js.

Tip If you add the item template elsewhere in the project, you may need to update script and CSS references in page2.html.
Open page2.js and verify that the URI is correct in the define function. Here's what it should look like.
```
WinJS.UI.Pages.define("/pages/page2/page2.html", {
    // . . . 
},
```

In this section, we add code to navigate between the pages. The navigation app we're creating uses a button-click event to move from one page to another. The template style sheet for the app (ui.css) automatically updates the button with the look of a Windows Store app.

Hh920268.wedge(en-us,WIN.10).gif To add navigation code

In Solution Explorer, open home.html.

In the SECTION element, add a button as shown here.

<section aria-label="Main content" role="main">
  <p>Content goes here.</p>
  <button class="navButton" title="Nav" >Next Page</button>
</section>

To set button characteristics specific to the page, open home.css.

Add this section to home.css.

.navButton {
    width: 10%;
    height: 10%;
}

Open home.js.
Add event-handling code that uses the WinJS.Navigation.navigate function to move to the new page. The nextPage function should be in the same scope as the ready function, so the code looks like this (with the comma added after ready).
```
WinJS.UI.Pages.define("/pages/home/home.html", {
    // . . .
    ready: function (element, options) {
        // . . .
    },

    nextPage: function () {
        WinJS.Navigation.navigate("/pages/page2/page2.html");
    }
});
```
The code in navigator.js is hooked up to the events that are generated when you call WinJS.Navigation.navigate, and loads the new page content.
In home.js, add an event listener for the button to the ready function, as shown in the following code. For more info on the use of ready in the project and item templates, see Navigation model.

To retrieve the element, we'll use querySelector instead of document.getElementByID.

Tip The templates use class names to identify elements in page controls. There can be more than one instance of a single page control present on the page (though that isn't the case in this example), and using IDs in page controls could result in multiple elements that have the same ID. Using querySelector and CSS class names prevents potential naming conflicts while ensuring that the correct DOM elements are found.

After you add the code, the function looks like this.
```
ready: function(element, options) {
  // TODO: Initialize the fragment here.
  var elem = element.querySelector('.navButton');
  elem.addEventListener('click', this.nextPage.bind(this));
},
```
Press F5 to run the app. When you click the Next Page button, page2.html loads and displays its default HTML content.

Test the app

Hh920268.wedge(en-us,WIN.10).gif To test the app

Press F5 to run the app.
When the app loads, click the Next Page button. page2.html loads and displays its default HTML content.

You can click the Back button to return to the first page of the app.