Share via

FlipView.itemTemplate property

  • Article

Gets or sets a Template or function that defines the HTML for each item's page.

Syntax

<div data-win-control="WinJS.UI.FlipView" data-win-options="{ itemTemplate : value}">
</div>

var itemTemplate = flipView.itemTemplate;
flipView.itemTemplate = itemTemplate;

Property value

Type: Object

A Template or a templating function you define that describes the HTML for each FlipView item. We recommend that the HTML generated for each item has a single root element. For more info about the syntax for the templating function, see the Templating function syntax section. Setting this property is required if you want to style FlipView items.

Remarks

Templating function syntax

When you define a templating function, it must take these parameters:

  • itemPromise
    WinJS.UI.IItemPromise

    A promise for the IItem to render. With a synchronous datasource, the IItemPromise is usually complete by the time the templating function gets called, but with an asynchronous datasource, it will complete at some time in the future.

The templating function must return either a Document Object Model (DOM) element that is the rendered item or an object that contains these properties:

  • element
    HTMLElement or WinJS.Promise

    The root element of a DOM tree for the item, or a promise that returns the root element for the item.

  • renderComplete
    WinJS.Promise

    A promise that completes when the item is fully rendered. Use this function to update element with the item's data.

Adding interactive elements to an item template

The item template can contain most other controls, but it can't contain a ListView or another FlipView.

Normally, when the user interacts with an element, the FlipView captures that interaction and uses it to determine whether the user selected or invoked an item or is panning through items. For an interactive element, such as a control, to receive input, you must attach the win-interactive class to the interactive element or one of its parent elements. That element and its children receive the interaction and no longer trigger events for the FlipView.

When you attach the win-interactive to an element in a item template, be sure that the element doesn't fill the entire item, otherwise the user won't have a way to select or invoke that item.

To add interactive elements to your item template, you must use a templating function instead of a WinJS.Binding.Template.

Examples

These examples show how to create different types of templates and templating functions. The examples use this data source, defined in its own JavaScript file named defaultData.js:

(function () {
    "use strict";

    var array = [
        { type: "item", title: "Cliff", picture: "images/Cliff.jpg" },
        { type: "item", title: "Grapes", picture: "images/Grapes.jpg" },
        { type: "item", title: "Rainier", picture: "images/Rainier.jpg" },
        { type: "item", title: "Sunset", picture: "images/Sunset.jpg" },
        { type: "item", title: "Valley", picture: "images/Valley.jpg" }
    ];
    var bindingList = new WinJS.Binding.List(array);

    WinJS.Namespace.define("DefaultData", {
        bindingList: bindingList,
        array: array
    });

    var e = DefaultData.bindingList.dataSource;
})();

The first example shows how to create a WinJS.Binding.Template declaratively.

<div id="simpleItemTemplate" 
     data-win-control="WinJS.Binding.Template" 
     style="display: none">
    <div style="width: 480px; height: 310px;">
        <img src="#" 
             data-win-bind="src: picture; alt: title"
             style="height: 270px; width: 480px;"  />       
        <div data-win-bind="innerText: title" 
             style="height:40px; padding: 5px;">
        </div>     
    </div>
</div>

<div id="basicFlipView" 
    style="width: 480px; height: 310px; border: solid 1px black; margin: 40px"
    data-win-control="WinJS.UI.FlipView"
    data-win-options="{ itemDataSource: DefaultData.bindingList.dataSource, itemTemplate: select('#simpleItemTemplate') }">
</div>

The next examples show two different types of templating functions for two different FlipView controls. Here is the HTML file that declares the FlipView controls :

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>templateFunctionExamples</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <link href="templateFunctionExamples.css" rel="stylesheet" />
    <script src="templateFunctionExamples.js"></script>
</head>
<body>
        <div id="renderingFunctionFlipView1" 
            style="width: 480px; height: 310px; border: solid 1px black; margin: 40px"
            data-win-control="WinJS.UI.FlipView"
            data-win-options="{ itemDataSource: DefaultData.bindingList.dataSource }">
        </div>   

        <div id="renderingFunctionFlipView2" 
            style="width: 480px; height: 310px; border: solid 1px black; margin: 40px"
            data-win-control="WinJS.UI.FlipView"
            data-win-options="{ itemDataSource: DefaultData.bindingList.dataSource }">
        </div>     
 
</body>
</html>

Here is the corresponding JavaScript that sets the itemTemplate property of each FlipView:

WinJS.UI.Pages.define("/pages/templateFunctionExamples/templateFunctionExamples.html", {
    // This function is called whenever a user navigates to this page. It
    // populates the page elements with the app's data.
    ready: function (element, options) {
        // TODO: Initialize the page here.

        var renderingFunctionFlipView1 = element.querySelector("#renderingFunctionFlipView1").winControl;
        renderingFunctionFlipView1.itemTemplate = simpleRenderer;

        var renderingFunctionFlipView2 = element.querySelector("#renderingFunctionFlipView2").winControl;
        renderingFunctionFlipView2.itemTemplate = placeholderRenderer;



    },

    unload: function () {
        // TODO: Respond to navigations away from this page.
    },

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

        // TODO: Respond to changes in viewState.
    }
});

The first templating function, simpleRenderer, takes an IItemPromise as a parameter. It waits for the IItemPromise to complete, then returns the HTML representation of the item.

//
// Simple renderer templating function
//
// Blocks the UI while waiting for the item data.
//
function simpleRenderer(itemPromise) {

    // Wait for the itemPromise to complete to access the data.
    return itemPromise.then(function (item) {
        // root element for the item
        var element = document.createElement("div");
        element.style.height = "310px";
        element.style.width = "480px";

        // Using innerHTML is usually faster than creating 
        // the DOM with createElement and appendChild.
        element.innerHTML =
            "<img style='height: 270px; width: 480px;' src='" + item.data.picture + "' alt='" + item.data.title + "' /> " +
            "<div style='height: 40px; padding: 5px'>" + item.data.title + "</div>";
        return element;
    });
}

The second templating function, placeholderRenderer, improves on the first templating function by creating and immediately returning a placeholder element and updating it once the data item becomes available. It does this by returning an object that contains two properties:

  • element
    HTMLElement

    The HTML element that is the placeholder for the item.

  • renderComplete
    IItemPromise

    A promise that completes when the item is ready. Use this function to update the placeholder element with the item's data.

Using the placeholder approach keeps your app responsive while the FlipView generates its items. Creating a placeholder is especially important when you're retrieving data from the web.

//
// Placeholder renderer templating function
//
// This templating function does not wait for item data.
// It immediately returns a placeholder element for the item.
// Then when item data is available, it updates the element.
//
function placeholderRenderer(itemPromise) {

    // Create a basic template for the item that doesn't depend on the item's data.
    var element = document.createElement("div");
    element.style.height = "310px";
    element.style.width = "480px";
    element.innerHTML = "<div class='content'>Loading...</div>";

    // Return the element as the placeholder 
    // and use a callback to update it when data is available.
    return {
        element: element,

        // Specifies a promise that completes when rendering is complete.
        // itemPromise will complete when the item's data is available.
        renderComplete: itemPromise.then(function (item) {

            // mutate the element to include the data
            element.innerHTML =
                "<img style='height: 270px; width: 480px;' src='" +
                item.data.picture +
                "' alt='" + item.data.title + "' /> " +
                "<div style='height: 40px; padding: 5px'>" +
                item.data.title + "</div>";
        })
    };
}

Requirements

Minimum WinJS version

WinJS 3.0

Namespace

WinJS.UI

See also

FlipView