How to create a templating function (HTML)
[ 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 create a templating function that generates items for a ListView.
What you need to know
Technologies
Prerequisites
- We assume that you can create a basic Windows app using JavaScript that uses WinJS controls. For instructions on getting started with WinJS controls, see the Quickstart: adding WinJS controls and styles.
Instructions
Step 1: About templating functions
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.
Step 2: Create a simple rendering function
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;
});
};
Remarks
For more examples, see the ListView item templates sample.