Free Trial Buy

Methods

This section describes the methods used to manipulate the DataSource.

cancel(operationId)

Cancels the load operation with a specific identifier.

Return Value:

Boolean

true if operation is canceled; false if it was not found.

You can access the load operation identifier using the operationId field extending the Promise object returned by the load() or reload() method.

JavaScript
var loadPromise = dataSource.load();
loadPromise.done(function(result) {
    . . .
});
. . .
dataSource.cancel(loadPromise.operationId);
NOTE
The cancel(operationId) method does not interrupt the HTTP request.

dispose()

Disposes all resources associated with this DataSource.

Use this method only if you created the DataSource manually (not via a widget).

filter()

Gets the filter option's value.

Return Value:

Object

A filter expression; described in the Filtering section.

filter(filterExpr)

Sets the filter option's value.

Parameters:
filterExpr:

Object

A filter expression; described in the Filtering section.
Pass null to clear filtering settings.

JavaScript
dataSource.filter("age", ">", 18);

group()

Gets the group option's value.

Return Value:

Object

A group expression; described in the Grouping section.

group(groupExpr)

Sets the group option's value.

Parameters:
groupExpr:

Object

A group expression; described in the Grouping section.

JavaScript
dataSource.group("age");

isLastPage()

Checks whether the count of items on the current page is less than the pageSize. Takes effect only with enabled paging.

Return Value:

Boolean

true if the item count is less than the pageSize; otherwise false.

isLoaded()

Checks whether data is loaded in the DataSource.

Return Value:

Boolean

true if data is loaded; otherwise false.

isLoading()

Checks whether the DataSource is being loaded.

Return Value:

Boolean

true if the DataSource is being loaded; otherwise false.

items()

Gets data items the DataSource currently operate.

Return Value:

Array<any>

The data items.

key()

Gets the value of the underlying Store's key option.

Return Value:

Object

|

String

|

Number

A key expression.

This method is actually a shortcut to the key option of the underlying Store. Using this method is equivalent to using dataSource.store().key().

See Also

load()

Starts loading data.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

Use the following code to access the loaded data.

JavaScript
dataSource.load()
    .done(function(result) {
        // 'result' contains the loaded data
    })
    .fail(function(error) {
        // handle error
    });

The Promise object returned by the load() method is extended by the operationId field. Pass its value to the cancel(operationId) method to cancel the invoked operation.

JavaScript
var loadPromise = dataSource.load();
loadPromise.done(function(result) {
    . . .
});
. . .
dataSource.cancel(loadPromise.operationId);

loadOptions()

Returns an object that would be passed to the load() method of the underlying Store according to the current data shaping option values of the current DataSource instance.

Return Value:

Object

A data shaping configuration object.

off(eventName)

Detaches all event handlers from a single event.

Parameters:
eventName:

String

The event's name.

Return Value:

Object

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from a single event.

Parameters:
eventName:

String

The event's name.

eventHandler:

function

The event's handler.

Return Value:

Object

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to an event.

Parameters:
eventName:

String

The event's name.

eventHandler:

function

The event's handler.

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

See Also

on(events)

Subscribes to events.

Parameters:
events:

Object

Events with their handlers: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

pageIndex()

Gets the current page index.

Return Value:

Number

A zero-based page index.

pageIndex(newIndex)

Sets the index of the page that should be loaded on the next call of the load() method.

Parameters:
newIndex:

Number

A zero-based page index.

pageSize()

Gets the page size.

Return Value:

Number

The page size.

pageSize(value)

Sets the page size.

Parameters:
value:

Number

A new page size value.

paginate()

Gets the paginate option's value.

Return Value:

Boolean

The option's value.

paginate(value)

Sets the paginate option's value.

Parameters:
value:

Boolean

A new value.

reload()

Clears currently loaded DataSource items and calls the load() method.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after loading is completed and rejected after loading failed. It is a native Promise or a jQuery.Promise when you use jQuery.

The Promise object returned by the reload() method is extended by the operationId field. Pass its value to the cancel(operationId) method to cancel the invoked operation.

JavaScript
var reloadPromise = dataSource.reload();
reloadPromise.done(function(result) {
    . . .
});
. . .
dataSource.cancel(reloadPromise.operationId);

requireTotalCount()

Gets the requireTotalCount option's value.

Return Value:

Boolean

The option's value.

requireTotalCount(value)

Sets the requireTotalCount option's value.

Parameters:
value:

Boolean

A new value.

searchExpr()

Gets the searchExpr option's value.

Return Value:

getter

|

Array<getter>

The option's value; described in the Getters and Setters section.

See Also

searchExpr(expr)

Sets the searchExpr option's value.

Parameters:
expr:

getter

|

Array<getter>

A new value; described in the Getters and Setters section.

JavaScript
dataSource.searchExpr("firstName");
dataSource.searchOperation("contains");
dataSource.searchValue("Jo");
See Also

searchOperation()

Gets the searchOperation option's value.

Return Value:

String

The option's value.

For more information on searching, refer to the Search Api section of the Data Layer article.

searchOperation(op)

Sets the searchOperation option's value.

Parameters:
op:

String

A new value. Can be one of the following: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains" and "notcontains".

JavaScript
dataSource.searchExpr("firstName");
dataSource.searchOperation("contains");
dataSource.searchValue("Jo");
See Also

searchValue()

Gets the searchValue option's value.

Return Value: any

The option's value.

For more information on searching, refer to the Search Api section of the Data Layer article.

searchValue(value)

Sets the searchValue option's value.

Parameters:
value: any

A new value.

JavaScript
dataSource.searchValue("Jo");

For more information on searching, refer to the Search Api section of the Data Layer article.

select()

Gets the select option's value.

Return Value: any

The current select expression; described in the Select Expressions section.

select(expr)

Sets the select option's value.

Parameters:
expr: any

A select expression; described in the Select Expressions section.

JavaScript
dataSource.select("firstName", "lastName", "age");

sort()

Gets the sort option's value.

Return Value: any

The current sort expression; described in the Sorting section.

sort(sortExpr)

Sets the sort option's value.

Parameters:
sortExpr: any

A sort expression; described in the Sorting section.

JavaScript
dataSource.sort("firstName");

store()

Gets the underlying Store instance.

Return Value:

Object

A Store object.

totalCount()

Returns the number of data items available in an underlying Store after the last load() operation without paging.

Return Value:

Number

The number of items.

To use this method, set the requireTotalCount option to true.