Quickstart: Adding a nav bar (NavBar)

Article
04/18/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how to add a navigation bar (also called a "nav bar" or "top app bar") to your Windows Store app using JavaScript. The Windows Library for JavaScript (WinJS) includes NavBar, NavBarCommand, and NavBarContainer controls to help you build a single-page navigation app.

Note The NavBar, NavBarCommand, and NavBarContainer controls are new for Windows 8.1. In Windows 8, use the AppBar control and the placement property to provide a nav bar.

Most Microsoft Visual Studio 2013 templates for Windows Store apps implement the navigation framework so you don't have to. These templates, including the Page Control item template (see Adding Page controls), include the BackButton control that lets you provide backward navigation for users.

Note Windows Store apps typically use one of two navigation patterns (flat and hierarchical). We recommend that you do not use the BackButton object in flat navigation apps. For details, see Navigation patterns.

The example we discuss here uses the Microsoft Visual Studio Blank App template. If you use the default styles and markup, the commands that you place in the NavBar control will be styled appropriately. This includes both image sprites and font glyphs for the icons of the commands.

For help choosing the best navigation pattern for your app, see Navigation patterns.

Also, you can see the Flat navigation and Hierarchical navigation patterns in action as part of our App features, start to finish series.

Prerequisites

Instructions

1. Create a new project by using the Blank App template

Start Visual Studio 2013.

Note When you run Visual Studio for the first time, it prompts you to obtain a developer license.
Choose File > New Project or click New Project from the Start Page tab. The New Project dialog box opens.
In the Installed pane, expand Templates, expand JavaScript, and then select the Windows Store app template type. The available project templates for JavaScript are displayed in the center pane of the dialog box.
In the center pane, select the Blank App project template.
In the Name text box, type a name for your project. The examples in this topic use Nav bar demo.
Click OK to create the project.

Your nav bar can be defined either declaratively in an HTML page or at run time in a JavaScript file that is loaded with the page. This example creates the nav bar declaratively in the HTML markup.

Open default.html and insert the following HTML into the body element. The nav bar should be a direct child of the body element.

Here, we declare a NavBar control that contains a NavBarContainer with two NavBarCommand controls.

Note While it is valid, we recommend that you not add NavBarCommand controls as immediate child elements of NavBar. Both button layout and keyboard accessibility are compromised.


<div id="navBar" data-win-control="WinJS.UI.NavBar">
  <div id="globalNav" data-win-control="WinJS.UI.NavBarContainer">
    <div data-win-control="WinJS.UI.NavBarCommand"
      data-win-options="{
                    label: 'Home',
        tooltip: 'Take me home',
        id:'homeButton',
        icon: WinJS.UI.AppBarIcon.home,
        location: '/pages/home/home.html',
      }">
    </div>
    <div data-win-control="WinJS.UI.NavBarCommand"
      data-win-options="{
                    label: 'Page 2',
        tooltip: 'Take me to Page 2',
        id:'page2Button',
        icon: WinJS.UI.AppBarIcon.page,
        location: '/pages/page2/page2.html',
      }">
    </div>
  </div>
</div>

The NavBarCommand objects declared in the markup inherently raise navigation events (Navigation.onnavigating and Navigation.onnavigated), so there's no need to add handler code to the NavBarCommand objects. Instead, you need to add handler code to the Navigation.onnavigating or Navigation.onnavigated events in the default.js file associated with the default.html file.

The example here adds a handler to the Navigation.onnavigated event. The handler gets the URL of the location being navigated to from the event object (defined in the location property of the data-win-options attribute of NavBarCommand). The handler then empties the content host (page control) of existing content and renders the new page in the host.

In Solution Explorer, open default.js from the js folder.

In default.js, replace the default code with the following.


(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;
    var nav = WinJS.Navigation;

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // Add your initialization code here.
            } else {
                // Restore app state here.
            }

            var start = WinJS.UI.processAll().
                then (function () {
                    return nav.navigate("/pages/home/home.html");
                                                                });

            args.setPromise(start);
        }
    };

    app.oncheckpoint = function (args) {
        // Add app suspension code here.
    };

    nav.onnavigated = function (evt) {
        var contentHost = 
            document.body.querySelector("#contenthost"),
            url = evt.detail.location;

        // Remove existing content from the host element.
        WinJS.Utilities.empty(contentHost);

        // Display the new page in the content host.
        WinJS.UI.Pages.render(url, contentHost);
    }

    app.start();
})();

4. Add two pages to navigate between

You can add these pages manually or through the Visual Studio Page Control item template, which provides all required markup and JavaScript code.

Dn376409.wedge(en-us,WIN.10).gif Manually add new pages to the project

In Solution Explorer, right-click the project name (Nav bar demo) and then choose Add, New Folder. Name the new folder "pages".
Right-click the pages folder that you just created and choose Add, New Folder. Name the new folder "home".
Create a second folder under pages. Name this folder "page2".
Right-click the home folder and choose Add, New HTML File. In the Add New Item dialog box, name this file "home.html" and choose Add.

Replace the default HTML with the following.
```
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>
    <p>Home</p>
</body>
</html>
```
Repeat the previous step for the page2 folder. Name the file "page2.html".

Replace the default HTML with the following.
```
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>
    <p>Page2</p>
</body>
</html>
```

Alternatively, you can use the JavaScript item templates for Windows Store apps in Visual Studio.

Dn376409.wedge(en-us,WIN.10).gif Use the Page Control item template to add new pages to the project

Create the pages folder with home and page2 subfolders as described previously.
Right-click the home folder and select Add > New Item.... The Add New Item dialog appears.
Select Page Control from the list. In the Name text box, type "home.html".
Click Add. A new PageControl object then appears in Solution Explorer.

The new PageControl includes three files:home.css, home.html, and home.js.

Note HTML files added in this way include code for the BackButton control. As stated previously, if you're using a flat navigation pattern, we recommend that you do not use the BackButton. So you can safely delete this code. For more detail, see Navigation patterns.
Right-click the page2 folder and select add Add > New Item.... The Add New Item dialog appears.
Select Page Control from the list. In the Name text box, type "page2.html".
Click Add. A new PageControl object then appears in Solution Explorer.

The new PageControl has three files:page2.css, page2.html, and page2.js.

5. Test the app

Press F5 to run the app. The app displays the Home page.
While the app runs, right-click anywhere in the app to bring up the nav bar and then choose Page2.

The Page2 page appears in the page control of the app.
Right-click again to bring up the nav bar and then choose Home.

The Home page appears in the page control of the app.

Summary and next steps

In this quickstart, you added a NavBar object with one NavBarContainer object and four NavBarCommand objects to your app. You also added a simple handler function for the Navigation.onnavigated event.

For a more complex hierarchical navigation and layout example, see our next tutorial on the Hub control.

Quickstart: Using a hub control for layout and navigation

Your first app - Part 3: PageControl objects and navigation

Adding app bars

Quickstart: Using single-page navigation

Quickstart: Using a hub control for layout and navigation

WinJS.Navigation Namespace

WinJS.UI.Hub object

WinJS.UI.AppBar object

WinJS.UI.NavBar object

WinJS.UI.BackButton object

HTML Hub control sample