JavaScript project templates for Windows Runtime apps

Article
01/05/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 project templates in Visual Studio help you build apps for Windows 8.1 devices by using HTML, CSS, and JavaScript. This topic describes each template, and helps you choose one. The topic includes implementation details about the navigation model, data model, and other features in the templates.

To learn about project templates for XAML, see C#, VB, and C++ project templates for Windows Store apps.

Roadmap: How does this topic relate to others? See Roadmap for using JavaScript.

Take a look at the templates

To get the templates for HTML and JavaScript:

You need a version of Visual Studio that supports Windows development; see Get the Tools.
To get the Windows app templates for Windows 8.1, you need Windows 8.1 Update or later and Microsoft Visual Studio 2013 Update 2 or later.

In Visual Studio, select File, then New, then Project to open the New Project dialog box. The templates for Windows 8.1 are available under JavaScript, the Windows, then Windows 8.

Windows Universal app templates for Windows 8.1

Visual Studio 2013 Update 2 includes JavaScript project templates that support developing both Windows Phone Store apps and Windows Store apps using shared code. A Windows Universal app for Windows 8.1 is an app that is built from shared code using a universal app template (two separate app packages are created when you build the project). The universal app templates for Windows 8.1 include:

One Windows Phone Store app project, named appName.Phone. Each project has a separate app package for upload to its respective Store.
One Windows Store app project, named appName.Windows.
One appName.Shared folder to store shared code. By default, all JavaScript files for the project are shared. HTML and CSS files can also be shared.

The universal app templates include:

Hub/Pivot project template (Windows 8.1)
Navigation project template (Windows 8.1)
Blank project template (Windows 8.1)

To handle behavior differences between the platforms in shared code:

Test whether a feature is supported before using it. For example, with different UI, you could check whether a platform-specific DOM element is present before using it.
If testing for a feature doesn't work well in a particular scenario, use the WinJS.Utilities.isPhone property to identify the current platform.
Some UI controls such as Pivot and SettingsFlyout are platform-specific. To support differences in UI, use separate HTML files, and move the separate files into the platform-specific project.
When you have a JavaScript file open in the shared folder, a context switcher drop-down list allows you to quickly change the targeted version of the Windows Library for JavaScript. This provides IntelliSense specific to the targeted version of the library.

Tip To change the build and deployment target, such as switching from the Windows Phone Emulator to the Simulator, choose Set as StartUp Project from the context menu for one of the projects.

To add a Windows Phone project to an existing Windows Store solution:

In Solution Explorer in Visual Studio, select the Windows Store project.
From the shortcut menu, choose Add Windows Phone 8.1.

Visual Studio adds the Windows Phone project and the folder for shared code to the solution. The new Windows Phone project is always a blank project template.

Tip Similarly, if you start with a Windows Phone project, you can add a Windows Store project to the solution.
If your Windows Store apps is not based on the Blank template, you will need to investigate whether the Blank template is the right starting point for the Windows Phone project, or whether you need to create a Windows Phone project separately and port the files to the new shared project. For an app based on the Hub template for Windows Store apps, the Pivot template for Windows Phone is the recommended starting point. If your app is based on the Grid or Split template, extra work will be required to port the app to a shared project, and the Pivot template may or may not work as a starting point.

To look at a sample app ported from the Hub template to the Hub/Pivot universal app template, see JSON Web reader that uses the Hub/Pivot template.

For in-depth information on porting an app to Windows Phone, see Porting your Windows Runtime app to Windows Phone.

Hub/Pivot project template for Windows Universal apps (Windows 8.1)

Use the Hub/Pivot project template to create a shared solution for a Windows Phone Store app and a Windows Store app that displays content in a horizontally panning view and provides a variety of ways to access content. Example Hub/Pivot apps include shopping apps, news apps, sports apps, and media hub apps.

By default, a Hub/Pivot app displays several sections in a horizontal layout. Each section represents a category of content such as new items, highlighted items, and categories of items. If the user chooses an item from one of the section views, a full-page view shows details about the item. This illustration shows section 4 on Windows Phone Emulator.

For info on the UX guidelines for the hub navigation pattern, see Navigation patterns.

Project files for the Hub/Pivot template

The Hub/Pivot App template includes the following files:

All the common files such as default.html and navigator.js.
hub.html, which is a container page for the individual sections, or pages, of the app (HubSection or PivotItem controls, depending on the project).
sectionNumberPage.html, which contains the markup for an individual pivot page. For example, section1Page.html contains the markup for the first pivot page or hub section page. On some pages, users can choose an item to view information about that item.
section.html, which shows a category of items and is specific to a Windows Store app. Users can choose an item to open the full-page view of that item.
item.html, which is the full-page view for an item.
A JavaScript and CSS file corresponding to each page in the app.
phone.css, which specifies CSS styles for the content host page and for the enitre app as a whole.
hubPhone.css, which specifies CSS styles for the pivot control and pivot pages. These styles override the styles set in hub.css.
A CSS file that is specific to each page in the app, such as hub.css.

How the Hub/Pivot template works

The sections of the Hub/Pivot template are intended to provide examples of content rather than content recommendations. Sections can be added and removed easily to fit the app content requirements.

In the Windows Phone project, each section is a separate PivotItem in a Pivot control. In the Windows project, each section is a separate HubSection control.

The sections of the template include static content, so it is easy to provide globalized resources. The sample resource file provides localized strings for the en-us locale.

For more info about the Hub/Pivot template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic
Navigation model in this topic
Adding data to a project template
Handling display changes in this topic
CSS styles in this topic

For an example that shows how to customize the Hub/Pivot template to add dynamic data to the app sections, see JSON Web reader that uses the Hub/Pivot template. For more info about the data model and how to customize it for a Windows Runtime app app, see the topic about adding data.

Hub project template for Windows Store apps (Windows 8.1)

Use the Hub project template to create a Windows Store app that displays content in a horizontally panning view that provides a variety of ways to access content. Example Hub apps include shopping apps, news apps, sports apps, and media hub apps. The Hub temple is a single-platform version of the Hub/Pivot template.

By default, a Hub app displays a home page that shows several sections in a horizontal layout. Each section represents content such as new items, highlighted items, and categories of items. If the user taps an interactive section heading (indicated by a ">" after the heading), the app opens the section page, which lists the items that are associated with that section. If the user chooses an item from either the home page or the section page, a full-page view shows details about the item. This illustration shows a home page that has at least three sections.

For info on the UX guidelines for the hub navigation pattern, see Navigation patterns.

Project files for the Hub template

The Hub App template includes the following files:

All the common files such as default.html and navigator.js.
hub.html, which shows the sections and items on the home page. Users can choose an item to open information about that item, or they can choose a section label to open information about that section.
item.html, which is the full-page view for an item.
section.html, which shows a category of items and is specific to a Windows Store app. Users can choose an item to open the full-page view of that item.
A JavaScript and CSS file corresponding to each page in the app.

How the Hub template works

The sections of the Hub template are intended to provide examples of content rather than recommendations about what type of content to include. Sections can be added and removed easily to fit the app content requirements.

The sections of the template include static content, so it is easy to provide globalized resources. The sample resource file provides localized strings for the en-us locale.

For more info about the Hub template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic
Navigation model in this topic
Adding data to a project template
Handling display changes in this topic
CSS styles in this topic

For an example that shows how to customize the Hub template to add dynamic data to the hub sections, see JSON Web reader that uses the Hub template. For more info about the data model and how to customize it for the Hub template, see the topic about adding data.

Pivot project template for Windows Phone Store apps (Windows Phone 8.1)

The Pivot template is a single-platform version of the Hub/Pivot template.

The Pivot App template provides a quick way to manage multiple views or pages. You can use it to filter large datasets, view multiple data sets, or switch app views. The Pivot template implements a Pivot control that contains individual PivotItem controls, each of which represents a pivot page. The Pivot control provides built-in support for touch interaction and navigation.

Project files for the Pivot template

The Pivot App template includes the following files:

All the common files such as default.html and navigator.js.
hub.html, which is a container page for the individual pivot pages (PivotItem controls).
sectionNumberPage.html, which contains the markup for an individual pivot page. For example, section1Page.html contains the markup for the first pivot page. On some pages, users can choose an item to view information about that item.
item.html, which is the full-page view for an item.
A JavaScript and CSS file corresponding to each page in the app.
phone.css, which specifies CSS styles for the content host page and for the app as a whole.
hubPhone.css, which specifies CSS styles for the pivot control and pivot pages. These styles override styles set in hub.css.

How the Pivot template works

The sections of the Pivot template are intended to provide examples of content rather than content recommendations. Sections, implemented as PivotItem controls, can be added and removed easily to fit the app content requirements.

The sections of the template include static content, so it is easy to provide globalized resources. The sample resource file provides localized strings for the en-us locale.

For more info about the Pivot template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic
Navigation model in this topic
Adding data to a project template
Handling display changes in this topic
CSS styles in this topic

For more info about the data model and how to customize it for a Windows Runtime app, see the topic about adding data and see JSON Web reader that uses the Hub/Pivot template.

The Navigation App template provides basic navigation by using the navigation model recommended for Windows Runtime apps. The template contains only one minimal page fragment to which you can easily add more page fragments by using the Page Control item template. You can then add your own content.

The Navigation template is available as a Windows Universal app for Windows Phone and Windows Store, or as a single-platform app.

The Navigation app defaults to a home page that displays a "Welcome" title, as shown here.

The Navigation App template includes the following files:

Most of the common files such as default.html and navigator.js.
home.html, which is the home page. It displays a "Welcome" title. In a universal app template, this file is shared.
home.js, which specifies behavior that's associated with the home page. In a universal app template, this file is shared.
home.css, which specifies CSS styles for the home page. When you use the Navigation template for a Windows Universal app, each project includes this file.

For more info about the Navigation template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic
Navigation model in this topic
Handling display changes in this topic
CSS styles in this topic

To add pages to the app, use the Page Control item template. For an example of adding a Page Control, see Adding a Page Control item template.

For a simple implementation of the Navigation template, see Button-Tab Navigator sample. This sample app includes some customizations of the navigation control.

If you need to include special behavior to handle layout changes in the Navigation template, we recommend that you use the same pattern used in the Grid and Split templates, which is to implement updateLayout in the HTML pages. For more info, see Handling display changes. Support for updateLayout is provided in the shared navigation model.

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.

Grid project template for Windows Store apps (Windows 8.1)

The Grid App template is a great way to start a Windows Store app that you can customize to enable users to browse through categories to find content in which they will want to fully immerse themselves. Examples include shopping apps, news apps, and photo or video apps. This template uses the JavaScriptnavigation model that is recommended for Windows Store apps.

The Grid app defaults to a home page that shows a list of groups. A group represents a named set of items, such as a part of a virtual department store that has individual retail items. If the user selects a group, the app opens the group details page, which has a list of the items on the right side. The user can select an item from either the home page or the group details page. This opens a full-page view that shows the item details. The home page is shown here.

Project files for the Grid template

The Grid App template includes the following files:

All the common files such as default.html and navigator.js.
groupedItems.html, which is the home page. It enables the user to view the groups and items, and either select an item to navigate to the full-page item view, or a select a group label to navigate to the group details page.
groupDetail.html, which enables the user to view group details on the left and items on the right, and select an item to navigate to the full-page item view.
itemDetail.html, which is the full-page view for an item.
A JavaScript file and CSS file corresponding to each page in the app, such as groupedItems.js.

How the Grid template works

For more info about the Grid template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic
Navigation model in this topic
Adding data to a project template
Handling display changes in this topic
CSS styles in this topic

The topic about adding data includes an example that shows how to add dynamic data to the Grid template and bind the data to the UI.

Split project template for Windows Store apps (Windows 8.1)

The Split App template is a great way to start creating a Windows Store app that you can customize to enable users to view a list of items and item details in a two-column view, where users might want to switch quickly among the items, and where the list might be updated dynamically. Examples include a news reader, a sports scores app, or an email app. This template uses the JavaScript navigation model that's recommended for Windows Store apps.

The Split app defaults to a home page that shows a list of groups. A group is a named set of items, like a news source that provides news stories. When the user selects a group by tapping or clicking it, the app opens the split-view page, with items on the left and details for the current item on the right. The split-view page is shown here.

The split-view page displays a two-column view (or master/detail view), where the details on the right side change when the user selects items on the left side. Again, imagine a list of news stories on the left side and the actual stories on the right side.

Project files for the Split template

The Split App template includes the following files:

All the common files such as default.html and navigator.js.
items.html, which is the home page. It enables the user to select a group to navigate to the app's split-view page.
split.html, which is the split-view page. It defines two sections—one for the list of items on the left and another for the item details on the right.
A JavaScript and CSS file corresponding to each page in the app, such as split.js and split.css.

How the Split template works

For more info about the Split template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic
Navigation model in this topic
Adding data to a project template
Handling display changes in this topic
CSS styles in this topic

The topic about the adding data includes an example that shows how to add dynamic data to the Split template and bind the data to the UI.

For an example that shows how to add search to the Split template, see Adding a Search Contract item template.

Blank project template for Windows Runtime apps (Windows 8.1)

The Blank App template provides a minimal Windows Runtime app app that compiles and runs, but contains no user interface controls or data. When you run an app that's based on the Blank project template, you see a black screen that contains placeholder text.

The Blank template is available as a universal app template for Windows Phone Store app and Windows Store app, or as a single-platform app.

Project files for the Blank template

The Blank App template includes the following files:

Most of the common files such as default.html and package.appxmanifest.

How the Blank template works

For more info about the Blank template implementation, see:

Common project template files in this topic
Common coding features in this topic
App lifecycle in this topic

The overall behavior and appearance of the Blank template is created by a CSS style sheet: ui-dark.css. You can change this reference in your HTML pages to ui-light.css. For more info, see CSS styles.

Common project template files

The following files are common to most of the project templates.

File	Description
default.html	This page is loaded first. For template apps that include the single-page navigation model, this page provides markup for the content host (where each page is loaded into the main window). In the universal app templates, each project includes this file.
navigator.js	Implements the single-page navigation model for the JavaScript project templates. The Blank project template does not include this file. Typically, you do not need to customize the navigation behavior implemented in the templates. However, the navigation control (navigator.js) is implemented as a standard project file so that you can make modifications if needed. For more info, see the following: How to customize the navigation control Button-Tab Navigator sample
data.js	Provides a data source object (a WinJS.Binding.List) that exposes the data to the rest of the app. This file includes sample data. For more info on the data model, see Customizing data in a project template. The Navigation and Blank project templates do not include this file.
package.appxmanifest	Describes the app package for Windows Store and Windows Phone Store apps. In a universal app template, each project includes this file.
PFX file	This file is used to sign the appxmanifest file. It is included as a project file to support building Windows Store apps from the command line.
default.js	Specifies how the app behaves when it's started. In the universal app templates, each project includes this file.
default.css	Specifies CSS styles for the app. In the universal app templates, each project includes this file.
Various image files	Image files included by default include splashscreen.png for the splash screen image, and storelogo.png, which is used for Windows Store, and other files.
resources.json	A sample resource file that contains localization strings.

Common coding features

The following features are common to all of the project templates:

Each JavaScript file wraps code in a self-executing anonymous function, as follows:
```
(function () {
    // . . .
})();
```
Members added inside the anonymous function are private, but you can make them public using the WinJS.Namespace.define function. The use of the anonymous function changes the way you need to write some code, such as when adding your own event handlers. For more info, see Coding basic apps.
Each JavaScript file specifies the use of strict mode with the "use strict" statement. For more info, see Strict Mode in the JavaScript Language Reference.
Strict declarative processing is always on. You must use WinJS.Utilities.markSupportedForProcessing to specify that a function is allowed to use declarative processing.

XML Documentation Comments are used in a few places in the JavaScript files to provide a more complete IntelliSense experience. For more info, see JavaScript IntelliSense.

App lifecycle

The implementation of the app lifecycle is the same for all of the JavaScript project templates for Windows Runtime apps. The app lifecycle begins when the app starts and ends when the app is closed. The project templates include a generic pattern for managing the app lifecycle. When you create an app that's based on a project template, you might need to include code to handle additional scenarios, such as handling data when the app is suspended or terminated.

The default.html file is set as the start page for each template. The corresponding JavaScript file for default.html includes the following call to WinJS.Application.start, which starts dispatching app events.

var app = WinJS.Application;
// . . .
app.start();

The best place to add code related to app lifecycle management is in default.js. The implementation of default.js is the same for all of the project templates. This file includes code to handle the WinJS onactivated event. This event is raised when Windows Runtime activation occurs. The code in the onactivated event handler checks whether the app was started from the Windows Start screen and calls WinJS.UI.processAll. The processAll function loads all the controls that include the data-win-control attribute in the DIV element of the control. Here's the code that contains the processAll function.

app.addEventListener("activated", function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // . . .
        } else {
            // . . .
        }
        // . . .
        }
        // . . .

        // . . .
        var p = ui.processAll().then(function () {
            return nav.navigate(nav.location || Application.navigator.home, nav.state);
        }).then(function () {
            return sched.requestDrain(sched.Priority.aboveNormal + 1);
        }).then(function () {
            ui.enableAnimations();
        });

        args.setPromise(p);
    }
});

If you have code that needs to run when the app sets up its initial state, you should include that code in the handler for the WinJS onactivated event. You might also need to include additional code if the app has been reactivated after being suspended. Add this code where indicated by the code comments.

if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
    // TODO: This application has been newly launched. Initialize
    // your application here.
} else {
    // TODO: This application has been reactivated from suspension.
    // Restore application state here.
}

As mentioned earlier, the templates don't include code to handle suspending the app. To handle this app state in your code, you can add code to the WinJS oncheckpoint event handler, shown here in default.js, or add code to register for the Windows Runtime suspending event (which calls oncheckpoint).

app.oncheckpoint = function (args) {
    // TODO: This application is about to be suspended. Save any state
    // that needs to persist across suspensions here. If you need to 
    // complete an asynchronous operation before your application is 
    // suspended, call args.setPromise().
    app.sessionState.history = nav.history;
};

You can use WinJS or Windows Runtime events, or a combination of both, to manage the app lifecycle. However, WinJS events and functions are sufficient for most apps. For more info, see How to suspend an app and How to resume an app.

Here are a few of the WinJS events and functions related to the app lifecycle:

The navigation model used in the Hub, Grid, Split, and Navigation App project templates is the recommended navigation model for Windows Runtime apps using HTML and JavaScript. In this model, HTML pages, loaded via the page's URI, get loaded into a single app-wide context. The pages are loaded 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.

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

To customize navigation in your apps using the single-page navigation model provided in the project templates:

Make sure your app includes navigator.js and the required content host markup for the navigation control in default.html (see below).
Make sure that each page is implemented as a PageControl. (You can use Visual Studio to add a PageControl item template.)
Implement initialization code for each page in either the ready or init function.
Call WinJS.Navigation.navigate to navigate to new pages.

Additional details about these requirements follow.

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 single-page navigation model and 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.

In the single-page navigation model used in the Grid, Split, Hub, and Navigation App templates, a DIV element that's declared as the app's navigation control provides the content host for all the app's pages. All page content is loaded into this DIV. The element, shown here, is included in default.html in the project templates.

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

The navigation control itself is implemented in navigator.js and for most apps does not need to be modified. The navigation control sets handlers for the WinJS.Navigation.onnavigated event.

Pages loaded into the content host must be PageControl objects. Each page control represents a modular unit of HTML, CSS, and JavaScript code. When the navigation control loads a page, it calls internally-defined methods of the IPageControlMembers interface, such as ready.

The project templates implement the ready function and, in some templates, the init function. The ready function is called when the page is loaded and fully processed.

Tip For more info on the page loading process, 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 into the content host DIV element. Several functions in the template pages call the navigate function of Windows Library for JavaScript (WinJS):

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

For more detail on implementing page navigation, see Navigating between pages.

CSS styles

The overall behavior and appearance of the templates is created by a CSS style sheet: ui-dark.css. This is a WinJS style sheet that defines the primary color scheme, fonts, and other style properties. The project reference is shown here:

<link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet">

You can change this reference in all of your HTML pages to ui-light.css, which is the recommended alternative color and style scheme for Windows Runtime apps:

<link href="//Microsoft.WinJS.1.0/css/ui-light.css" rel="stylesheet">

Most of the HTML pages in the Grid and Split project templates use one or more WinJS templates (which are not the same as Visual Studio project and item templates) to format and display multiple instances of data. For example, wherever a ListView control is present on a page, you'll find a WinJS template that has a class name of itemtemplate. The class names are used both to retrieve elements in the JavaScript files and to specify CSS. Here's the item template that's in items.html in the Split project template:

<div class="itemtemplate" data-win-control="WinJS.Binding.Template">
    <div class="item">
        <img class="item-image" src="#" data-win-bind="src: backgroundImage; alt: title" />
    <div class="item-overlay">
        <h4 class="item-title" 
            data-win-bind="textContent: title"></h4>
        <h6 class="item-subtitle win-type-ellipsis" 
            data-win-bind="textContent: subtitle"></h6>
    </div>
</div>

Important The itemtemplate template is used for any type of ListView item, which might be a group or an individual data item, depending on context.

The CSS styles that are associated with the HTML pages, along with their WinJS templates, are scoped CSS styles. The use of scoped styles limits the application of styles to particular pages. This can help to reduce the time it takes to fix problems that occur when the source of a particular CSS style isn't clear. An example of the use of scoped styles is shown here. This section of code, in items.css, shows CSS properties set for the preceding item template's IMG element. This element represents the associated image for each item in the ListView.

.itemspage .itemslist .item .item-image {
    -ms-grid-row-span: 2;
}

In the previous example, the itemspage entry sets the scope for the style, restricting the application of the CSS to elements that are in the itemspage DIV element declared in items.html. The itemslist entry further restricts the CSS to the main content section in the home page, and so on. The main content section in items.html, which declares the ListView, looks like this:

<div class="itemslist win-selectionstylefilled" 
    aria-label="List of groups" 
    data-win-control="WinJS.UI.ListView" 
    data-win-options="{ selectionMode: 'none' }">
</div>

Style sheet support for right-to-left writing systems is provided in the templates in Microsoft Visual Studio 2012 Update 1. The following example shows a CSS style for a group header displayed right-to-left in groupedItems.css (Grid template).

.groupeditemspage .groupeditemslist.win-rtl .group-header .group-chevron:before {
    content: "\E26C";
}

To use the right-to-left styles, you must include resources for a right-to-left language in your project, and Windows must be set to the correct language settings. For more info, see Quickstart: translating UI resources. For guidelines on supporting right-to-left writing systems in Windows Runtime apps, see How to support bi-directional UI.

Handling display changes

The Hub, Grid, and Navigation templates do not implement special support for handling changes in display size or layout, beyond what is provided by the layout controls, but they do provide a basic framework to enable customization in response to changes in layout. Layout changes may be handled within the project template navigation model. For more info, see navigation model.

Tip If layout changes affect only the UI, you can usually handle these changes using @media queries in CSS files.

In navigator.js, the navigation control creates a handler for the window.onresize event.

window.onresize = this._resized.bind(this);

In the constructor code for PageControlNavigator, the onresize event maps eventually to the updateLayout function that's implemented in the JavaScript file associated with the current HTML page. At run time, the onresize event calls this function.

The implementation of updateLayout is specific to each page, but is typically not implemented in the project templates. This code shows the stub code for updateLayout in the section page of the Hub template.

updateLayout: function (element) {
    /// <param name="element" domElement="true" />

    // TODO: Respond to changes in layout.
},

The Split template does supports unique behavior related to display states. By default, the split-view page (split.html) in the Split template is a two-column view —the master/detail view. The Split template defines an alternative view called a single-column view, which it sets by checking the width of the root node of the document. The code that defines and sets the single-column view is in split.js. The _isSingleColumn function defines the single-column view:

_isSingleColumn: function () {
    return document.documentElement.offsetWidth <= 767;
},

Several different methods in split.js, such as _updateVisibility, call _isSingleColumn. The _updateVisibility function turns the visibility of the columns on and off, depending on whether the app is currently in single-column view and whether an item has been selected. _updateVisibility is called in split.js by the ready function when the page is loaded, and also by updateLayout when the resize event occurs. For more info, see split.js in the Split template.

For more info on handing layout changes, see Guidelines for window sizes and scaling to screens.

JavaScript project templates for Windows Runtime apps

Take a look at the templates

Windows Universal app templates for Windows 8.1

Hub/Pivot project template for Windows Universal apps (Windows 8.1)

Project files for the Hub/Pivot template

How the Hub/Pivot template works

Hub project template for Windows Store apps (Windows 8.1)

Pivot project template for Windows Phone Store apps (Windows Phone 8.1)

Navigation project template for Windows Runtime apps (Windows 8.1)

Project files for the Navigation template

How the Navigation template works

Grid project template for Windows Store apps (Windows 8.1)

Split project template for Windows Store apps (Windows 8.1)

Blank project template for Windows Runtime apps (Windows 8.1)

Project files for the Blank template

How the Blank template works

Common project template files

Common coding features

App lifecycle

Navigation model

CSS styles

Handling display changes

Additional resources