List.createGrouped method

Creates a live grouped projection over this list. As the list changes, the grouped projection reacts to those changes and may also change. The grouped projection sorts all the elements of the list to be in group-contiguous order. The grouped projection also contains a .groups property, which is a List representing the groups that were found in the list.

Syntax

var groupedSortedListProjection = list.createGrouped(groupKey, groupData, groupSorter);

Parameters

• groupKey
  Type: Function

  A function that accepts a single argument. The function is called with each element in the list, the function should return a string representing the group containing the element.

  This function must always return the same results, given the same inputs. The results should not depend on values that are subject to change. You must call notifyMutated each time an item changes. Do not batch change notifications.

• groupData
  Type: Function

  A function that accepts a single argument. The function is called once, on one element per group. It should return the value that should be set as the data of the .groups list element for this group. The data value usually serves as summary or header information for the group.

• groupSorter
  Type: Function

  A function that accepts two arguments. The function is called with pairs of group keys found in the list. It must return one of the following numeric values: negative if the first argument is less than the second (sorted before), zero if the two arguments are equivalent, positive if the first argument is greater than the second (sorted after).

Return value

Type: GroupedSortedListProjection**

A grouped projection over the list.

Examples

The following code shows how to use the createGrouped method. It takes a list of cats and dogs and creates two groups, one of cats and one of dogs.

<div id="groupsDiv"></div> 
<script type="text/javascript">
    var myList = new WinJS.Binding.List([
        { name: "Marley", species: "dog" },
        { name: "Lola", species: "cat" },
        { name: "Leo", species: "dog" },
        { name: "Izzy", species: "cat" },
        { name: "Ziggy", species: "cat" },
        { name: "Ruby", species: "dog" }
    ]);

    // Create a grouped list from the item data and the grouping functions
    var myGroupedList = myList.createGrouped(getGroupKey, getGroupData, compareGroups);

    var groups = myGroupedList.groups;
    var div = document.getElementById("groupsDiv");

    var i = groups.length;
    while (--i >= 0) {
        var group = groups.getItem(i);

        div.textContent += group.data.groupDescription + " ";

        var j = group.groupSize;
        var start = group.firstItemIndexHint;
        while (--j >= 0) {
            var item = myGroupedList.getItem(start + j);
            div.textContent += item.data.name + " ";;
        }
    }

    // Sorts the groups by first letter
    function compareGroups(left, right) {
        return left.toUpperCase().charCodeAt(0) - right.toUpperCase().charCodeAt(0);
    }

    // Gets the key of the group that an item belongs to
    function getGroupKey(dataItem) {
        return dataItem.species;
    }

    // Gets the data for a group
    function getGroupData(dataItem) {
        return {
            groupDescription: dataItem.species + " group";
        };
     }

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.Binding

See also

List