ListView.groupHeaderTemplate property

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 information, see the Remarks section.You must specify this property when using groups. The default value is null.

Remarks

To display group information, 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).

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

Requirements

See also

ListView

How to group items in a ListView

Quickstart: Adding a ListView

Build date: 12/5/2012