ListView.groupHeaderTemplate property

Article
01/26/2017

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

Syntax

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

var groupHeaderTemplate = listView.groupHeaderTemplate;
listView.groupHeaderTemplate = groupHeaderTemplate;

Property value

Type: Object

A WinJS.Binding.Template or a function that generates DOM elements for each group header. For more info, see the Remarks section. You must specify this property when using groups. The default value is null.

Remarks

To display group info, such as group headers and group boundaries, your ListView control's layout must be set to a GridLayout. For grouping to work at all, the ListView control's loadingBehavior property must be set to "randomaccess" (which is the default value).

For a walkthrough that shows you how to display groups in a ListView, see How to group items in a ListView.

Using a templating function

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

object renderItem(itemPromise, recycledElement)

itemPromise: a IItemPromise for the data for the group 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 Document Object Model (DOM) from a previous group header that can be reused to display new content. This parameter is optional.

If you use element recycling:
- Clear out the old group header's info before using the recycled element as a placeholder.
- If the HTML for a group header 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, 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 group header.
An object that contains these properties:
- element: the root element of a DOM tree for the group header, or a promise that when completed will return the root element for the group header.
- renderComplete: a Promise that completes when the group header is fully rendered.

For more info about using templating functions, see How to create a templating function.

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI