Telerik UI for Windows 8 HTML

The DataSource component exposes a number of methods for fetching and manipulating data. They are listed in the sections below.

This topic contains the following sections.

Methods for Fetching Data

The following table lists the methods that you can use to get data using DataSource.

Method

Arguments

Description

Example (ds is a DataSource instance in all examples below)

fetch

None

Fetches data using the current filter/sort/group/paging information. If data is not available or remote operations are enabled, data is requested through the transport, otherwise operations are executed over the available data.

JavaScript Copy imageCopy
ds.sort = { field: "UnitPrice", dir: "asc" };
ds.pageSize = 3;
ds.page = 1;
ds.fetch();

query

queryObj: An object containing page, sort, filter and group settings. The settings syntax is the same as when they are specified inside the DataSource constructor.

Executes a query over the data. Available operations are paging, sorting, filtering, grouping. If data is not available or remote operations are enabled, data is requested through the transport. Otherwise operations are executed over the available data.

JavaScript Copy imageCopy
var query = {
    sort: { field: "UnitPrice", dir: "asc" },
    group: { field: "CategoryID" },
    filter: { field: "UnitPrice", operator: "gt", value: 7 }
};
ds.query(query);

read

None

Reads the data into the DataSource using the transport.read definition.

JavaScript Copy imageCopy
var dataSource = new Telerik.Data.DataSource({
    transport: {
        read: {
            url: "http://services.odata.org/Northwind/Northwind.svc/Categories",
            dataType: "json"
        }
    },
    schema: {
        data: "value"
    }
});
dataSource.read().then(function () {
    //use result in the promise complete function
    grid.columns = []; //grid is an existing RadGrid control
    grid.dataSource = dataSource;
    grid.refresh();
});

Methods for Working with Data

This section lists the methods that can be used to access specific items from the DataSource underlying data and get information about them.

Method

Arguments

Description

Example (ds is a DataSource instance in all examples below)

at

index: The numeric index at which the item is placed in the DataSource.

Returns the data record at the specified index.

JavaScript Copy imageCopy
var productName = ds.at(3).ProductName;
info.innerText = "Found " + productName + ".";

getById

id: The ID of the item to retrieve. The ID of a model is defined through the schema.model.id option of the dataSource.

Retrieves an item from the DataSource by a given ID.

JavaScript Copy imageCopy
var productName = ds.getById(2).ProductName;
info.innerText = "Found " + productName + ".";

getByUid

uid: The uid of the item to retrieve. You need to first get ahold of the item to access and store its uid.

Retrieves an item from the DataSource by its uid field.

JavaScript Copy imageCopy
var item = ds.at(2);
info.innerText = "Before sort found " + item.ProductName;
var uid = item.uid;
ds.sort = { field: "ProductName", dir: "desc" };
ds.fetch().then(function () {
    var searchedItem = ds.getByUid(uid);
    info.innerHTML += "<p>After sort found " + searchedItem.ProductName;
});

indexOf

item: An object taken from the DataSource underlying data.

Retrieves the index of a specified object from the underlying data. The object must be a part of the DataSource instance.

JavaScript Copy imageCopy
var item = ds.getById(2);
info.innerText = "Found product " + item.ProductName + " at position " + ds.indexOf(item);

Methods for Modifying Data

This section lists methods that are used when inserting and removing data from DataSource. They include methods that check the current state of the data, cancel or push applied changes.

Method

Arguments

Description

Example (ds is a DataSource instance in all examples below)

add

item: A JavaScript object containing the new data.

Adds a new data item to the DataSource.

JavaScript Copy imageCopy
ds.add({
    ProductID: 22,
    ProductName: "Grandma's Pancakes",
    CategoryID: 3,
    UnitPrice: 12
});

insert

index: The index to insert the new item at.

item: A JavaScript object containing the new data.

Inserts a new item into the DataSource at the specified index.

JavaScript Copy imageCopy
ds.insert(20, {
    ProductID: 21,
    ProductName: "Fruit salad",
    CategoryID: 3,
    UnitPrice: 15
});

remove

item: An object taken from the DataSource underlying data.

Removes the specified item from the DataSource.

JavaScript Copy imageCopy
var itemToRemove = ds.getById(20);
ds.remove(itemToRemove);

hasChanges

None

Gets a boolean value indicating whether data in the DataSource has changed.

JavaScript Copy imageCopy
info.innerText = "Has unsaved changes: " + ds.hasChanges();

cancelChanges

None

Cancels any changes made to the data since the last sync.

JavaScript Copy imageCopy
if (ds.hasChanges()) {
    ds.cancelChanges();
}

sync

None

Synchronizes changes through the transport. Any pending CRUD operations will be sent to the web service if such is used. The DataSource will send one request per item change and change type (create, update, delete).

JavaScript Copy imageCopy
var itemToRemove = ds.getById(20);
ds.remove(itemToRemove);
ds.sync();

See Also