ListView.itemTemplate property

Gets or sets the Template or function that creates the Document Object Model (DOM) elements for each item in the itemDataSource. Each item can contain multiple elements, but it must have a single root element.

Syntax

<div data-win-control="WinJS.UI.ListView" data-win-options="{ itemTemplate : select('value')}">
</div>

var itemTemplate = listView.itemTemplate;
listView.itemTemplate = itemTemplate;

Property value

Type: Object

A WinJS.Binding.Template or a function that generates DOM elements for each item. For more information, see the Remarks section. You must set this property if you want to style the ListView items. The default value is null.

Remarks

Items in a ListView control can contain other controls, but they can't contain a FlipView or another ListView.

Using a Template to Display Items

The item Template should bind to the properties of the data that you want to display.

For example, the following code creates a set of items that have title, description, and picture properties.

var myData = [

{ title: "Banana", description: "Banana Frozen Yogurt", picture: "images/banana.jpg" }, 
{ title: "Orange", description: "Orange Sherbet", picture: "images/orange.jpg" }, 
{ title: "Vanilla", description: "Vanilla Ice Cream", picture: "images/vanilla.jpg" }, 
{ title: "Mint", description: "Mint Gelato", picture: "images/mint.jpg" },
{ title: "Strawberry", description: "Strawberry Sorbet", picture: "images/strawberry.jpg" }
];

An item template defines the HTML markup that is displayed for each data item in your ListView. It has a single root element and can contain as many HTML elements as you want. To use one of those elements to display your data, you set the data-win-bind attribute on that element.

The data-win-bind attribute uses the following syntax:

For example, to bind the src property of an img to the "picture" field, use the following syntax:

<img data-win-bind="src : picture" />

To set multiple properties, separate them with a comma:

The following example creates an item template that displays the title, text, and picture of each data item.

    <div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
        <div>

            <!-- Displays the "picture" field. -->
            <img data-win-bind="alt: title; src: picture" />
            <div>

                <!-- Displays the "title" field. -->
                <h4 data-win-bind="innerText: title"></h4>

                <!-- Displays the "text" field. --> 
                <h6 data-win-bind="innerText: description"></h6>
            </div>
        </div>
    </div>     

    <div id="basicListView" data-win-control="WinJS.UI.ListView" 
        data-win-options="{itemDataSource : DataExample.itemList.dataSource, itemTemplate: select('#mediumListIconTextTemplate')}">
    </div>

Using a function to display items

Instead of defining an item template in markup, you can create a function that renders each list item. The render function takes these parameters:

object renderItem(itemPromise, recycledElement)

• itemPromise: a IItemPromise for the data for the item to render. With a synchronous datasource, the IItemPromise is usually complete, but with an async datasource, it will complete at some time in the future.
• recycledElement : the DOM from a previous item that can be reused to display new content. This parameter is optional.

  If you use element recycling:

  • Clear out the old item's info before using the recycled element as a placeholder. When you use recycling, the old item will likely contain old data and state from the last time it was used. Clear or hide the state before reusing the recycled element.

    For example, if the template contains a photo and you want to reuse the img element but don't have the new URL yet, hide the img by setting its opacity to 0 because it might contain a photo from the old data. When you have the URL of the new photo, you can update the img element and change its opacity back to 1.

  • If the HTML for an item has conditional state based on the item data, be sure to reset it when it's recycled.
  • When recycling elements, minimize structural changes to the DOM. If the recycledElement is not appropriate for re-use, then ignore it and create a new element from scratch, and the recycledElement will be garbage collected.

  Warning  The ListView can change the structure of recycledElement, so always test that child elements exist before trying to access them.

The render function must return either:

• The root element of a DOM tree for the item.

• An object that contains these properties:

  • element: the root element of a DOM tree for the item, or a promise that when completed will return the root element for the item.
  • renderComplete: a Promise that completes when the item is fully rendered.

This example retrieves a ListView named templateFunctionListView and sets its itemTemplate property with an item template function that displays the title, text, and picture of each data item.

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            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.
            }
            args.setPromise(WinJS.UI.processAll().then(function () {
                var lView = document.getElementById("templateFunctionListView").winControl;
                lView.itemTemplate = itemTemplateFunction;

            }));

        }
    };

   function itemTemplateFunction(itemPromise) {

       return itemPromise.then(function (item) {
           var div = document.createElement("div");

           var img = document.createElement("img");
           img.src = item.data.picture;
           img.alt = item.data.title;
           div.appendChild(img);

           var childDiv = document.createElement("div");

           var title = document.createElement("h4");
           title.innerText = item.data.title;
           childDiv.appendChild(title);

           var desc = document.createElement("h6");
           desc.innerText = item.data.text;
           childDiv.appendChild(desc);

           div.appendChild(childDiv);
           
           return div;
       });
    };

Adding interactive elements to an item template

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

Normally, when the user interacts with an element, the ListView 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 ListView.

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.

Requirements

See also

ListView

Quickstart: Adding a ListView

Build date: 12/5/2012