WinJS.UI.IListDataSource interface

Article
01/26/2017

Provides access to a data source and enables you to bind, change, add, remove, and move items in that data source.

IListDataSource is an interface. To create an IListDataSource, you create an object that implements this interface. For more info, see the Remarks section.

Members

The IListDataSource interface has these types of members:

Events
Methods

Events

The IListDataSource interface has these events.

Event	Description
statuschanged	Occurs when the status of the IListDataSource changes.

Methods

The IListDataSource interface has these methods.

Method	Description
beginEdits	Notifies the IListDataSource that a sequence of edits is about to begin. The IListDataSource will defer notifications until endEdits is called.
change	Overwrites the data of the specified item.
createListBinding	Creates an IListBinding that can retrieve items from the IListDataSource, enumerate the contents of the IListDataSource object's data, and optionally register for change notifications.
endEdits	Notifies the IListDataSource that the batch of edits that began with the last beginEdits call has completed. The IListDataSource will submit notifications for any changes that occurred between the beginEdits and endEdits calls as a batch and resume normal change notifications.
getCount	Retrieves the number of items in the data source.
insertAfter	Inserts a new item after another item.
insertAtEnd	Adds an item to the end of the data source.
insertAtStart	Adds an item to the beginning of the data source.
insertBefore	Inserts an item before another item.
invalidateAll	Indicates that all previous data obtained from the IListDataAdapter is invalid and should be refreshed.
itemFromDescription	Retrieves the item that has the specified description.
itemFromIndex	Retrieves the item at the specified index.
itemFromKey	Retrieves the item with the specified key.
moveAfter	Moves an item to just after another item.
moveBefore	Moves an item before another item.
moveToEnd	Moves an item to the end of the data source.
moveToStart	Moves the specified item to the beginning of the data source.
remove	Removes the specified item from the data source.

Remarks

A IListDataSource connects a control (such as a ListView) to an IListDataAdapter. The IListDataSource manipulates the IListDataAdapter, which does the work of actually manipulating and retrieving data.

The Windows Library for JavaScript provides several types of IListDataSource objects that you can use:

You can use a List to create an IListDataSource from an array of data by calling the List object's dataSource property.
You can use a StorageDataSource to access information about files and directories.

You can also create your own custom data source that connects to some other type of data provider, such as a web service or database. For instructions, see How to create a custom data source.

Examples

This example creates a List ("itemList") from an array of items. Then it uses the WinJS.Namespace.define method to publicly expose the List as a part of the "DataExample" namespace.

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);

})();

The next example creates an item template and a ListView. Because itemList is a List and not an IListDataSource, it uses the itemList object's dataSource property to retrieve an IListDataSource version of the List:

itemDataSource : DataExample.itemList.dataSource

Here's the full code:

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

For a full walkthrough of the code and more info about creating your first ListView, see Quickstart: Add a ListView.

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI

Partager via