Methods

This section describes the methods used to manipulate the DataSource.

cancel(operationId)

Cancels the load operation associated with the specified identifier.

Return Value: Boolean
Indicates whether the operation is successfully canceled (*true*) or was not found (*false*).

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

Returns the current filter option value.

Return Value: Object
A filter expression.

For information on filter expressions, refer to the Filtering section of the Data Layer article.

filter(filterExpr)

Sets the filter option value.

Parameters:
filterExpr: Object
A filter expression.
JavaScript
dataSource.filter("age", ">", 18);

For information on filter expressions, refer to the Filtering section of the Data Layer article.

To clear filtering conditions, call this method with null as a parameter.

group()

Returns the current group option value.

Return Value: Object
A group expression.

For information on group expressions, refer to the Grouping section of the Data Layer article.

group(groupExpr)

Sets the group option value.

Parameters:
groupExpr: Object
A group expression.
JavaScript
dataSource.group("age");

For information on group expressions, refer to the Grouping section of the Data Layer article.

isLastPage()

Indicates whether or not the current page contains fewer items than the number of items specified by the pageSize configuration option.

Return Value: Boolean
If the loaded page size is less then the specified page size, the value is true; otherwise, the value is false.
NOTE
If paging is disabled, the method always returns true.

isLoaded()

Indicates whether or not at least one load() method execution has successfully finished.

Return Value: Boolean
If the load() method execution has successfully finished, it returns true; otherwise, it returns false.

isLoading()

Indicates whether or not the DataSource is currently being loaded.

Return Value: Boolean
If the DataSource is being loaded, it returns true; otherwise, it returns false.

items()

Returns the array of items currently operated by the DataSource.

Return Value: Array
The array of items operated by the DataSource.

key()

Returns the key expression specified by the key configuration option of the underlying Store.

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: jQuery.Promise
A Promise of the jQuery.Deferred object resolved when the data has loaded.

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 the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
Return Value: Object
The object for which this method is called.
See Also

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
eventHandler: function
The handler to be detached from the specified event.
Return Value: Object
The object for which this method is called.
See Also

on(eventName, eventHandler)

Subscribes to a specified event.

Parameters:
eventName: String
The name of the event to be subscribed.
eventHandler: function
An event handler for the specified event.
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 the specified events.

Parameters:
events: Object
An object of the following structure: { "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()

Specifies the index of the currently loaded page.

Return Value: Number
A zero-based index.

pageIndex(newIndex)

Specifies the index of the page to be loaded during the next load() method execution.

Parameters:
newIndex: Number
A zero-based index.

pageSize()

Returns the current pageSize option value.

Return Value: Number
The current page size value.

pageSize(value)

Sets the pageSize option value.

Parameters:
value: Number
The page size value.

paginate()

Returns the current paginate option value.

Return Value: Boolean
The current value of the paginate option.

paginate(value)

Sets the paginate option value.

Parameters:
value: Boolean
The new paginate option value.

reload()

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

Return Value: jQuery.Promise
A Promise of a jQuery Deferred object, which is resolved when loading is complete and rejected when loading fails.

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

Returns the current requireTotalCount option value.

Return Value: Boolean
The current value of the requireTotalCount option.

requireTotalCount(value)

Sets the requireTotalCount option value.

Parameters:
value: Boolean
The new requireTotalCount option value.

searchExpr()

Returns the searchExpr option value.

Return Value: getter|Array
A getter representing a search expression.

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

searchExpr(expr)

Sets the searchExpr option value.

Parameters:
expr: getter|Array
A getter representing a search expression.
JavaScript
dataSource.searchExpr("firstName");
dataSource.searchOperation("contains");
dataSource.searchValue("Jo");

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

searchOperation()

Returns the currently specified search operation.

Return Value: String
A search operation expression.

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

searchOperation(op)

Sets the current search operation.

Parameters:
op: String
A search operation expression.

The available search operations are: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains" and "notcontains".

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

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

searchValue()

Returns the searchValue option value.

Return Value: any
The value to which the search expression value is compared.

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

searchValue(value)

Sets the searchValue option value.

Parameters:
value: any
The value to which the search expression value is compared.
JavaScript
dataSource.searchValue("Jo");

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

select()

Returns the current select option value.

Return Value: any
A select expression.

For information on select expressions, refer to the Select Expressions section of the Data Layer article.

select(expr)

Sets the select option value.

Parameters:
expr: any
A select expression.
JavaScript
dataSource.select("firstName", "lastName", "age");

For information on select expressions, refer to the Select Expressions section of the Data Layer article.

sort()

Returns the current sort option value.

Return Value: any
A sort expression.

For information on sort expressions, refer to the Sorting section of the Data Layer article.

sort(sortExpr)

Sets the sort option value.

Parameters:
sortExpr: any
A sort expression.
JavaScript
dataSource.sort("firstName");

For information on sort expressions, refer to the Sorting section of the Data Layer article.

store()

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