JavaScript project templates for Windows Store apps

[This documentation is preliminary and is subject to change.]

This topic provides in-depth info about the project templates for Windows Store apps built for Windows using JavaScript. In addition to a brief summary of each template, implementation details about the navigation model, data model, handling of view state, and other details are provided. Many of these implementation details apply to more than one template.

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.

Important  The information in this topic has been updated for Windows 8.1 Preview.

To get the templates, you need a version of Visual Studio that supports Windows development. For more info, see Get the Tools.

For info about Visual Studio and Blend templates for other languages, see Jump start your app using templates (C#/VB/C++).

Hub project template for Windows Store apps

By using the Hub project template, you can create a Windows Store app that displays content in a horizontally panning view and visually engages users by providing a variety of ways to access content. For info on the UX guidelines for the hub navigation pattern, see Navigation design for Windows Store apps. The main Hub page provides different sections to represent content such as new items, highlighted items, and categories of items. Example apps include shopping apps, news apps, sports apps, and media hub apps, and you can find this template in Microsoft Visual Studio 2013 Preview.

By default, a Hub app displays a home page that shows several sections in a horizontal layout. If the user taps an interactive section heading (indicated by a ">"), the app opens the section page, which lists the items that are associated with the 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.

Project files for the Hub template

The Hub App template includes these HTML files:

• default.html, which is loaded first and provides markup for the content host (where each page is loaded into the main window).
• 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.
• section.html, which shows a category of items. 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.

The template includes these JavaScript files:

• default.js, which specifies how the app behaves when itstarts.
• hub.js, which specifies behavior that's associated with the home page.
• section.js, which specifies behavior that's associated with the section page.
• item.js, which specifies behavior that's associated with the full-page view of an item.
• navigator.js, which implements the navigation model for the Windows Store app JavaScript templates.
• data.js, which is the data source object that exposes the data to the rest of the app.

The template includes these CSS files:

• default.css, which specifies CSS styles for the content host page and for the app as a whole.
• hub.css, which specifies CSS styles for the home page.
• section.css, which specifies CSS styles for the section page.
• item.css, which specifies CSS styles for the full-page item view.

The Hub App template also includes the following files:

• package.appxmanifest, which describes the app package for Windows.
• A PFX file that is used to sign the appxmanifest file (this file is included as a project file to support building from the command prompt).
• Several image files, like splashscreen.scale-100.png for the splash screen image, and storelogo.scale-100.png, which is used for Windows Store.
• A sample resource file that contains localization strings (resources.resjson).

How the Hub template works

The sections of the Hub 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.

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 coding features
• App lifecycle
• Navigation model
• Handling view state
• CSS styles

Grid project template for Windows Store apps

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 JavaScript navigation 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 these HTML files:

• default.html, which is loaded first and provides markup for the content host (where each page is loaded into the main window).
• 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.

The template includes these JavaScript files:

• default.js, which specifies how the app behaves when it's started.
• groupedItems.js, which specifies behavior that's associated with the home page.
• groupDetail.js, which specifies behavior that's associated with the group details page.
• itemDetail.js, which specifies behavior that's associated with the full-page item view.
• navigator.js, which implements the navigation model for the Windows Store app JavaScript templates.
• data.js, which is the data source object that exposes the data to the rest of the app.

The template includes these CSS files:

• default.css, which specifies CSS styles for the content host page and for the app as a whole.
• groupedItems.css, which specifies CSS styles for the home page.
• groupDetail.css, which specifies CSS styles for the group details page.
• itemDetail.css, which specifies CSS styles for the full-page item view.

The Grid App template also includes the following files:

• package.appxmanifest, which describes the app package for Windows.
• A PFX file that is used to sign the appxmanifest file (this file is included as a project file to support building from the command line).
• Several image files, like splashscreen.png for the splash screen image, and storelogo.png, which is used for Windows Store.
• A sample resource file that contains localization strings (resources.resjson).

How the Grid template works

For more info about the Grid template implementation, see:

• Common coding features
• App lifecycle
• Navigation model
• Adding data to a project template
• Handling view state
• CSS styles

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

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 these HTML files:

• default.html, which is loaded first and provides markup for the content host (where each page is loaded into the main window).
• 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.

The template includes these JavaScript files:

• default.js, which specifies how the app behaves when it's started.
• items.js, which specifies behavior that's associated with the home page.
• split.js, which specifies behavior that's associated with the split-view page.
• navigator.js, which implements navigation for the Windows Store app JavaScript templates.
• data.js, which is the data-source object that exposes data to the app.

The template includes these CSS files:

• default.css, which specifies CSS styles for the content host page and for the app as a whole.
• items.css, which specifies CSS styles for the home page.
• split.css, which specifies CSS styles for the split-view page.

The Split App template also includes the following files:

• package.appxmanifest, which describes the app package for Windows.
• A PFX file that is used to sign the appxmanifest file (this file is included as a project file to support building from the command line).
• Several image files, like splashscreen.png for the splash screen image, and storelogo.png, which is used for Windows Store.

How the Split template works

For more info about the Split template implementation, see:

• Common coding features
• App lifecycle
• Navigation model
• Adding data to a project template
• Handling view state
• CSS styles

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.

Navigation project template for Windows Store apps

The Navigation App template provides basic navigation by using the navigation model recommended for Windows Store 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 app defaults to a home page that displays a "Welcome" title, as shown here.

Project files for the Navigation template

The Navigation App template includes these HTML files:

• default.html, which is loaded first and provides markup for the content host (where each page is loaded into the main window).
• home.html, which is the home page. It displays a "Welcome" title.

The template includes these JavaScript files:

• default.js, which specifies how the app behaves when it's started.
• home.js, which specifies behavior that's associated with the home page.
• navigator.js, which implements the navigation model for the Windows Store app JavaScript templates.

The template includes these CSS files:

• default.css, which specifies CSS styles for the content host page and for the app as a whole.
• home.css, which specifies CSS styles for the home page.

The Navigation App template also includes the following files:

• package.appxmanifest, which describes the app package for Windows.
• A PFX file that is used to sign the appxmanifest file (this file is included as a project file to support building from the command line).
• Several image files, like splashscreen.png for the splash screen image, and storelogo.png, which is used for Windows Store.

How the Navigation template works

For more info about the Navigation template implementation, see:

• Common coding features
• App lifecycle
• Navigation model
• CSS styles

If you need to include special handling of view state changes in the Navigation template, you must make changes to your code. 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 view state. Support for updateLayout is provided in the shared navigation model.

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.

Blank project template for Windows Store apps

The Blank App template provides a minimal Windows Store 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.

Project files for the Blank template

The Blank App template includes this HTML file:

• default.html, which is the home page of the app.

The template includes this JavaScript file:

• default.js, which specifies how the app behaves when it's started.

The template includes this CSS file:

• default.css, which specifies CSS styles for the app.

The Navigation App template also includes the following files:

• package.appxmanifest, which describes the app package for Windows.
• A PFX file that is used to sign the appxmanifest file (this file is included as a project file to support building from the command line).
• Several image files, like splashscreen.png for the splash screen image, and storelogo.png, which is used for Windows Store.

How the Blank template works

For more info about the Blank template implementation, see:

• Common coding features
• App lifecycle

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

  Copy

  
  (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.
• Default.js includes a call WinJS.Binding.optimizeBindingReferences. This function helps prevent memory leaks when declarative binding is used in an app, as is common in the templates.
• 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 Store 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 Windows Library for JavaScriptonactivated 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 {
            // . . .
        }
        // . . .
        }
        args.setPromise(WinJS.UI.processAll().then(function () {
            // The code in this section navigates to the current page, if one
            // is set, or the home page if a current page is not set.
            // . . .
        }));
    }
});

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 Windows Library for JavaScriptonactivated 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 Windows Library for JavaScriptoncheckpoint 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 Windows Library for JavaScript or Windows Runtime events, or a combination of both, to manage the app lifecycle. However, Windows Library for JavaScript 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 Windows Library for JavaScript events and functions related to the app lifecycle:

• activated
• loaded
• ready
• checkpoint
• unload
• sessionState

CSS styles

The overall behavior and appearance of the templates is created by a CSS style sheet: ui-dark.css. This is a Windows Library for JavaScript 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 Store 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 Windows Library for JavaScript 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 Windows Library for JavaScript 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 Windows Library for JavaScript 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 Store apps, see How to support bi-directional UI.

Handling view state

The Hub and Grid templates do not implement special support for different view states, 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 are handled within the project template navigation model. For more info, see navigation model.

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

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

Several functions in split.js also modify the Back button history or navigation behavior depending on the view state. The ready function and the updateLayout function modify the Back button history. The selectionChanged function, which is called when an item in the list view is selected, modifies the navigation behavior. For more info on managing view state, see Guidelines for layouts.

Build date: 6/21/2013