Share via


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