Quickstart: Using a hub control for layout and navigation

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 Hub control to your Windows Store app using JavaScript.

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 Microsoft Visual Studio Express 2013 for Windows.
From the Start Page tab, click New Project. The New Project dialog opens.
In the Installed pane, expand Templates and JavaScript, and click the Windows Store app template type. The available project templates for JavaScript are displayed in the center pane of the dialog.
In the center pane, pick the Blank App project template.
In the Name text box, type Hub demo.
Click OK to create the project.

2. Add the hub definition to the project

Define a Hub control either declaratively in an HTML page or at run time using JavaScript loaded with the page. This example creates the hub declaratively in the HTML markup.

Open default.html and insert the following HTML into the body element. The hub should be a direct child of the body element. It's a good idea to place global commands before contextual commands in the Document Object Model (DOM) in order to get the best layout when users resize your app.

This example adds a hub declaratively with three HubSection objects, where the second HubSection is the first visible section in the Hub. Use the default styles or write your own Cascading Style Sheets (CSS) for the Hub and HubSection controls.


<div data-win-control="WinJS.UI.Hub" id="hub"
    data-win-options="{
        sectionOnScreen : '1',
    }">
    <div data-win-control="WinJS.UI.HubSection"
        data-win-options="{
            header: 'Ancient Greek authors',
            isHeaderStatic: true
        }">
        My favorite authors of Ancient Greek (Homeric, Attic, Ionic):
        <ul>
            <li>Homer</li>
            <li>Herodotus</li>
            <li>Thucydides</li>
            <li>Plato</li>
        </ul>
    </div>
    <div data-win-control="WinJS.UI.HubSection"
        data-win-options="{
            header: 'Latin authors'
        }">
        <div>
            My favorite authors of works in Classical Latin:
            <ul>
                <li>Marcus Tullius Cicero</li>
                <li>Caius Julius Caesar</li>
                <li>Publius Virgilius Maro (Virgil)</li>
                <li>Titus Livius Patavinus (Livy)</li>
            </ul>
        </div>
    </div>
    <div data-win-control="WinJS.UI.HubSection"
        data-win-options="{
            header: 'English authors',
            isHeaderStatic: false
        }">
        My favorite authors of works in Middle and Early Modern English: 
        <ul>
            <li>Geoffrey Chaucer</li>
            <li>William Shakespeare</li>
            <li>Christopher Marlowe</li>
        </ul>
    </div>
</div>

3. Add code to handle Hub events

Two of the HubSection objects in this example have dynamic headers: when clicked, they raise the Hub.onheaderinvoked event by default. To set dynamic or static headers, use the HubSection.isHeaderStatic property, which is set to false by default.

In the Hub.onheaderinvoked event handler, the HubSection object or the index of the invoked HubSection object can be extracted from the event arguments (the index is zero-based).

The following example adds a handler to the Hub.onheaderinvoked event. The handler gets the index of the invoked HubSection and sets the Hub.sectionOnScreen value.

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

In the default.js file, replace the existing code with this code.


(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;
    var hub;

    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.
            }
            args.setPromise(WinJS.UI.processAll());
        }

        // Get the hub control from the HTML page and
        // add a handler to the headerInvoked event.
        hub = WinJS.Utilities.query("#hub")[0];
        hub.winControl.onheaderinvoked = onHeaderInvoked;
    };

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

    // When a HubSection header is clicked, call this code to
    // make the section completely visible within the hub.
    function onHeaderInvoked(args) {
        hub.winControl.sectionOnScreen = args.detail.index;
    }

    app.start();
})();

Set the runtime environment to Simulator and press F5 to run the app.
Change the resolution of the simulator window so the last hub section is partially off-screen when the hub page is panned to the left.
Click the header of the last, partially visible section in the hub to pan the hub page so that the hub section is fully visible.

4. Navigating within a hub app

Hub apps follow what is called a Hierarchical navigation pattern. For additional info about navigation user experiences in Windows Store apps, see Navigation patterns.

In apps that include a large content collection or many distinct sections of content for a user to explore, you typically want to provide a way for users to quickly navigate back the same way they came. Pages and section headings in a hub app can host BackButton controls. Each page can host a back button that remains hidden until you navigate to that page from another, whereupon the back button becomes visible on the page. The BackButton control can be created declaratively in the HTML of the page or at run time by using JavaScript.

The BackButton control doesn't require you to do a lot of work. In fact, most of the code associated with the back button's navigation functionality is built into the Windows Library for JavaScript (WinJS) platform. You just need to declare the control in your HTML markup as shown here.

<!DOCTYPE html>
<html>
<head>
    <title>home</title>
</head>
<body>
    <header role="banner">
        <button data-win-control="WinJS.UI.BackButton"></button>
        <h1 class="titlearea">Home</h1>
    </header>
</body>
</html>

Without styling, the BackButton control is displayed in a separate block above the page title. To achieve the Windows style where the back button appears inline with the title, you must add some custom CSS to your project. Specifically, you need to create a grid within the parent element (the <section> tag) that arranges the two elements side by side.

In default.css (in the css folder), add the following CSS code to adjust the layout of the BackButton control and title on the pages.

#contenthost {
    height: 100%;
    width: 100%;
}

header[role=banner] {
    display: -ms-grid;
    -ms-grid-columns: 37px 83px 1fr;
    -ms-grid-rows: 1fr;
}

    header[role=banner] button {
        -ms-grid-column: 2;
        margin-top: 57px;
    }

    header[role=banner] h1 {
        -ms-grid-column: 3;
        margin-top: 37px;
    }

Summary

In this quickstart, you added a Hub control with three HubSection objects. You also added a simple handler function to the Hub.onheaderinvoked event.

You also added a BackButton control to each page in the app.

For developers

Your first app - Part 3: PageControl objects and navigation

Adding app bars

Quickstart: Using single-page navigation

Quickstart: Adding a nav bar (NavBar)

WinJS.Navigation Namespace

WinJS.UI.Hub object

WinJS.UI.AppBar object

WinJS.UI.NavBar object

WinJS.UI.BackButton object

HTML Hub control sample