Methods

This section describes the methods used to manipulate the DataSource.

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.

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.

You can use this function in the loadingChanged event handler to obtain the current DataSource state.

JavaScript
dataSource.on("loadingChanged", function() {
    if (dataSource.isLoading())
        // loading has started
    else
        // loading is finished
});

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.

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

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

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.

For details on using methods for handling events, refer to the Handle Events topic.

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.

For details on using methods for handling events, refer to the Handle Events topic.

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.

For details on using methods for handling events, refer to the Handle Events topic.

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 at one method call. Available events are listed in the Events section.

For details on using methods for handling events, refer to the Handle Events topic.

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.

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: Object
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: Object
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: Object
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: Object
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: Object
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: Object
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: Object
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: Object
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.