DataSource

An object that provides access to a data web service or local data storage for collection container widgets.

Included in: dx.mobile.js, dx.web.js, dx.viz.js, dx.viz-web.js, dx.all.js
Type:

Object

A DataSource object is the connection between a collection container widget and the data provided by a web service or data stored locally. To create a DataSource instance, call its constructor and pass the configuration object to it.

JavaScript
var myDataSource = new DevExpress.data.DataSource(dataSourceConfig);

To associate a DataSource instance with a widget, pass this instance to the dataSource option of the widget.

HTML
<div data-bind="dxList: { dataSource: myDataSource }"></div>

You can also pass the DataSource configuration object to the dataSource option. In this case, the DataSource instance will be automatically created within the widget.

HTML
<div data-bind="dxList: { dataSource: dataSourceConfig }"></div>
NOTE
If you create a DataSource instance outside the widget, be sure to dispose of it when it is no longer used. If the DataSource is created within the widget, it will be disposed of automatically.

Refer to the Data Layer and Data Source Examples topics for more information about working with data in DevExtreme.

Configuration

This section describes configuration options used to configure the data source.

Name Description
customQueryParams

The bag of custom parameters passed to the query executed when the DataSource load operation is invoked.

expand

An array of the strings that represent the names of the navigation properties to be loaded simultaneously with the OData store's entity.

filter

Specifies data filtering conditions.

group

Specifies data grouping conditions.

map

The item mapping function.

onChanged

A handler for the changed event.

onLoadError

A handler for the loadError event.

onLoadingChanged

A handler for the loadingChanged event.

pageSize

Specifies the maximum number of items the page can contain.

paginate

Specifies whether a DataSource loads data by pages, or all items at once.

postProcess

The data post processing function.

requireTotalCount

Specifies whether or not the DataSource instance requests the total count of items available in the storage.

searchExpr

Specifies a value by which the required items are searched.

searchOperation

Specifies the comparison operation used to search for the required items.

searchValue

Specifies the value to which the search expression is compared.

select

Specifies the initial select option value.

sort

Specifies the initial sort option value.

store

Specifies the underlying Store instance used to access data.

NOTE
To create a DataSource instance that uses custom data access logic, pass the CustomStore configuration object to the DataSource constructor. As an example, consider the following synthetic implementation, which generates a read-only infinite list.
JavaScript
var infiniteListSource = new DevExpress.data.DataSource({
    load: function(loadOptions) {
        var result = [ ];
        for(var i = 0; i < loadOptions.take; i++)
            result.push({ id: 1 + loadOptions.skip + i });
        return result;
    },
    byKey: function(key) {
        return { id: key };
    }
});

Methods

This section describes the methods used to manipulate the DataSource.

Name Description
cancel(operationId)

Cancels the load operation associated with the specified identifier.

dispose()

Disposes all resources associated with this DataSource.

filter()

Returns the current filter option value.

filter(filterExpr)

Sets the filter option value.

group()

Returns the current group option value.

group(groupExpr)

Sets the group option value.

isLastPage()

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

isLoaded()

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

isLoading()

Indicates whether or not the DataSource is currently being loaded.

items()

Returns the array of items currently operated by the DataSource.

key()

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

load()

Starts loading data.

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.

off(eventName)

Detaches all event handlers from the specified event.

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

on(eventName, eventHandler)

Subscribes to a specified event.

on(events)

Subscribes to the specified events.

pageIndex()

Specifies the index of the currently loaded page.

pageIndex(newIndex)

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

pageSize()

Returns the current pageSize option value.

pageSize(value)

Sets the pageSize option value.

paginate()

Returns the current paginate option value.

paginate(value)

Sets the paginate option value.

reload()

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

requireTotalCount()

Returns the current requireTotalCount option value.

requireTotalCount(value)

Sets the requireTotalCount option value.

searchExpr()

Returns the searchExpr option value.

searchExpr(expr)

Sets the searchExpr option value.

searchOperation()

Returns the currently specified search operation.

searchOperation(op)

Sets the current search operation.

searchValue()

Returns the searchValue option value.

searchValue(value)

Sets the searchValue option value.

select()

Returns the current select option value.

select(expr)

Sets the select option value.

sort()

Returns the current sort option value.

sort(sortExpr)

Sets the sort option value.

store()

Returns the underlying Store instance.

totalCount()

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

Events

This section describes events raised by the DataSource object.

Name Description
changed

Fires after data is successfully loaded.

loadError

Fires when data loading is failed.

loadingChanged

Fires when the data loading status is changed.

To handle events, use one of the following methods.