WinJS.Binding.List object

Represents a list of objects that can be accessed by index or by a string key. Provides methods to search, sort, filter, and manipulate the data.

Syntax

var object = new WinJS.Binding.List(list, options);

Members

The List object has these types of members:

• Constructors
• Methods
• Properties

Constructors

The List object has these constructors.

Constructor	Description
List	Creates a List object.

 

Methods

The List object has these methods.

Method	Description
addEventListener	Adds an event listener.
bind	Links the specified action to the property specified in the name parameter. This function is invoked when the value of the property may have changed. It is not guaranteed that the action will be called only when a value has actually changed, nor is it guaranteed that the action will be called for every value change. The implementation of this function coalesces change notifications, such that multiple updates to a property value may result in only a single call to the specified action.
concat	Returns a new list consisting of a combination of two arrays.
createFiltered	Creates a live filtered projection over this list. As the list changes, the filtered projection reacts to those changes and may also change.
createGrouped	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.
createSorted	Creates a live sorted projection over this list. As the list changes, the sorted projection reacts to those changes and may also change.
dispatchEvent	Raises an event of the specified type and with additional properties.
dispose	Disconnects a WinJS.Binding.List projection from its underlying WinJS.Binding.List. It's only important to call this method when the WinJS.Binding.List projection and the WinJS.Binding.List have different lifetimes. (Call this method on the WinJS.Binding.List projection, not the underlying WinJS.Binding.List.)
every	Checks whether the specified callback function returns true for all elements in a list.
filter	Returns the elements of a list that meet the condition specified in a callback function.
forEach	Calls the specified callback function for each element in a list.
getAt	Gets the value at the specified index.
getItem	Gets a key/data pair for the specified list index.
getItemFromKey	Gets a key/data pair for the list item key specified.
indexOf	Gets the index of the first occurrence of the specified value in a list.
indexOfKey	Gets the index of the first occurrence of a key in a list.
join	Returns a string consisting of all the elements of a list separated by the specified separator string.
lastIndexOf	Gets the index of the last occurrence of the specified value in a list.
map	Calls the specified callback function on each element of a list, and returns an array that contains the results.
move	Moves the value at index to the specified position.
notify	Notifies listeners that a property value was updated.
notifyMutated	Forces the list to send a itemmutated notification to any listeners for the value at the specified index.
notifyReload	Forces the list to send a reload notification to any listeners.
pop	Removes the last element from a list and returns it.
push	Appends new element(s) to a list, and returns the new length of the list.
reduce	Accumulates a single result by calling the specified callback function for all elements in a list. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduceRight	Accumulates a single result by calling the specified callback function for all elements in a list, starting with the last member of the list. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
removeEventListener	Removes an event listener.
reverse	Returns a list with the elements reversed. This method reverses the elements of a list object in place. It does not create a new list object during execution.
setAt	Replaces the value at the specified index with a new value.
shift	Removes the first element from a list and returns it.
slice	Extracts a section of a list and returns a new list.
some	Checks whether the specified callback function returns true for any element of a list.
sort	Returns a list with the elements sorted. This method sorts the elements of a list object in place. It does not create a new list object during execution.
splice	Removes elements from a list and, if necessary, inserts new elements in their place, returning the deleted elements.
unbind	Removes one or more listeners from the notification list for a given property.
unshift	Appends new element(s) to a list, and returns the new length of the list.

 

Properties

The List object has these properties.

Property	Access type	Description
dataSource	Read-only	Gets the IListDataSource for the list. The only purpose of this property is to adapt a List to the data model that is used by ListView and FlipView.
groups	Read/write	Gets a List that is a projection of the groups that were identified in this list. This property is available only for GroupsListProjection objects.
length	Read/write	Gets or sets the length of the list, which is an integer value one higher than the highest element defined in the list.

 

Remarks

Use a List to create a bindable collection from an array of data. To use the List to provide data to a ListView or FlipView control, call the List object's itemDataSource to obtain an IListDataSource.

Examples

The following code shows how to connect a List to a ListView object. The DIV object displays the members of the list. Note that you must use the list's dataSource property to bind to the itemDataSource property of the ListView.

You can also connect a List to a FlipView object, which displays each member of the list separately. You can see how it works by changing data-win-control="WinJS.UI.ListView" to data-win-control="WinJS.UI.FlipView".

<div id="listDiv"  
    data-win-control="WinJS.UI.ListView" 
    data-win-options="{ itemDataSource : dataList.dataSource }">
</div>
<script type="text/javascript">

    var dataArray = [
        { name: "Marley", species: "dog" },
        { name: "Lola", species: "cat" },
        { name: "Leo", species: "dog" },
        { name: "Izzy", species: "cat" },
        { name: "Ziggy", species: "cat" },
        { name: "Ruby", species: "dog" }
    ];

    var dataList = new WinJS.Binding.List(dataArray);
    WinJS.UI.processAll();
</script>

The next example creates a more complex ListView that uses item templates.

This first example creates an item template and a ListView.

<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
    <div style="width: 282px; height: 70px; padding: 5px; overflow: hidden; display: -ms-grid;">

        <!-- Displays the "picture" field. -->
        <img data-win-bind="alt: title; src: picture"
            src="#"
            style="width: 60px; height: 60px; margin: 5px; -ms-grid-column: 1;" />
        <div style="margin: 5px; -ms-grid-column: 2">

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

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

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

The next example defines the data for the ListView in a separate JavaScript file. For the ListView to access the data, add a reference to the JavaScript file to the HTML page that contains the ListView.

// data.js
(function () {
    "use strict";

    var dataArray = [
    { title: "Basic banana", text: "Low-fat frozen yogurt", picture: "images/60banana.png" },
    { title: "Banana blast", text: "Ice cream", picture: "images/60banana.png" },
    { title: "Brilliant banana", text: "Frozen custard", picture: "images/60banana.png" },
    { title: "Orange surprise", text: "Sherbet", picture: "images/60orange.png" },
    { title: "Original orange", text: "Sherbet", picture: "images/60orange.png" },
    { title: "Vanilla", text: "Ice cream", picture: "images/60vanilla.png" },
    { title: "Very vanilla", text: "Frozen custard", picture: "images/60vanilla.png" },
    { title: "Marvelous mint", text: "Gelato", picture: "images/60mint.png" },
    { title: "Succulent strawberry", text: "Sorbet", picture: "images/60strawberry.png" }
    ];

    var itemList = new WinJS.Binding.List(dataArray);

    // Create a namespace to make the data publicly
    // accessible. 
    var publicMembers =
        {
            itemList: itemList
        };
    WinJS.Namespace.define("DataExample", publicMembers);

})();

For more information about using ListView and FlipView controls with List objects, see Quickstart: Adding a ListView and Quickstart: Adding a FlipView.

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.Binding

See also

Quickstart: Adding a ListView

Quickstart: Adding a FlipView