Adding a Page Control item template

This topic demonstrates how to add the Page Control item template to a basic 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 2012 to simplify your app development.

The project we create here uses the Navigation project template, which is a minimal template that enables you to implement custom navigation within a predefined navigation model. The navigation model in the template, like the one in the Split and Grid project templates, provides a single content host page (default.html) and enables navigation among logical pages that are loaded into the content host. We recommend using the Page Control item template when adding pages to the Grid, Split, and Navigation project templates.

The Page Control item template creates a new page control in your app. A page control uses separate HTML and JavaScript files to define a reusable piece of user interface.

Creating the navigation app

First, we'll create an app by using the Navigation template.

1. In Visual Studio, click File > New Project.
2. In the left pane of the New Project dialog box, expand the JavaScript node.
3. In the center pane, select Navigation App.
4. 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.

5. To run the program, click Debug > Start Debugging, or press F5. The following page content appears: "Welcome to NavApp!"
6. Press SHIFT + F5 to stop debugging and return to Visual Studio.

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

1. In Solution Explorer, right-click the pages folder and click Add > New Folder.
2. Name the new folder page2.
3. Right-click the page2 folder, and then click Add > New Item.
4. In the Add New Item dialog box, select Page Control in the middle pane.
5. Name the page page2.html and click 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.

6. Open page2.js and verify that the URI is correct in the define function. Here's what it should look like:
   JavaScript

   Copy

   
   WinJS.UI.Pages.define("/pages/page2/page2.html", {
       // . . . 
   },
   
   

Adding navigation code

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.

1. In Solution Explorer, open home.html.
2. In the SECTION element within the BODY element, add a button, as shown here:
   HTML

   Copy

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

3. To set button characteristics specific to the page, open home.css.
4. Add this section to home.css:
   CSS

   Copy

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

5. Open home.js.
6. 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):
   JavaScript

   Copy

   
   
   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.

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

   JavaScript

   Copy

   
   
   ready: function(element, options) {
     // TODO: Initialize the fragment here.
     var elem = element.querySelector('.navButton');
     elem.addEventListener('click', this.nextPage.bind(this));
   },
   
   
   

8. Press F5 to run the app. When you 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.

Related topics

JavaScript project templates for Windows Store apps

JavaScript item templates for Windows Store apps

QuickStart: using single page navigation

Adding a Page Control item template (C#, VB, and C++)

Build date: 3/11/2013