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

Module: data/data_source

Export: default

Type:

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.

When using a widget as an ASP.NET MVC Control, declare the options of the DataSource in the DataSourceOptions() method.

Razor C#

Razor VB

@(Html.DevExtreme().DataGrid()
    .ID("dataGrid")
    .DataSource(d => d
        // ...
        // Data access is configured here
    )
    .DataSourceOptions(o => o
        .Filter("['ProductID', '>', 10]")
        .Sort("LastName", false)
    )
)

@(Html.DevExtreme().DataGrid() _
    .ID("dataGrid") _
    .DataSource(Function(d)
        Return d.
            @* Data access is configured here *@
    End Function) _
    .DataSourceOptions(Sub(o)
        o.Filter("['ProductID', '>', 10]") _
         .Sort("LastName", False)
    End Sub)
)

For information on how to configure data access in ASP.NET MVC Controls, see the Data Binding topic.

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	Specifies the navigation properties that are loaded with the OData entity. Available only for the ODataStore.
filter	Specifies data filtering conditions.
group	Specifies data grouping options.
map	Specifies an 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	Specifies a post processing function.
requireTotalCount	Specifies whether or not the DataSource instance requests the total count of items available in the storage.
searchExpr	Specifies the fields to search.
searchOperation	Specifies the comparison operation used in searching. The following values are accepted: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".
searchValue	Specifies the value to which the search expression is compared.
select	Specifies the fields to select from data objects.
sort	Specifies data sorting options.
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 with a specific identifier.
dispose()	Disposes all resources associated with this DataSource.
filter()	Gets the filter option's value.
filter(filterExpr)	Sets the filter option's value.
group()	Gets the group option's value.
group(groupExpr)	Sets the group option's value.
isLastPage()	Checks whether the count of items on the current page is less than the pageSize. Takes effect only with enabled paging.
isLoaded()	Checks whether data is loaded in the DataSource.
isLoading()	Checks whether the DataSource is being loaded.
items()	Gets data items the DataSource currently operate.
key()	Gets the value of the underlying Store's key option.
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 a single event.
off(eventName, eventHandler)	Detaches a particular event handler from a single event.
on(eventName, eventHandler)	Subscribes to an event.
on(events)	Subscribes to events.
pageIndex()	Gets the current page index.
pageIndex(newIndex)	Sets the index of the page that should be loaded on the next call of the load() method.
pageSize()	Gets the page size.
pageSize(value)	Sets the page size.
paginate()	Gets the paginate option's value.
paginate(value)	Sets the paginate option's value.
reload()	Clears currently loaded DataSource items and calls the load() method.
requireTotalCount()	Gets the requireTotalCount option's value.
requireTotalCount(value)	Sets the requireTotalCount option's value.
searchExpr()	Gets the searchExpr option's value.
searchExpr(expr)	Sets the searchExpr option's value.
searchOperation()	Gets the searchOperation option's value.
searchOperation(op)	Sets the searchOperation option's value.
searchValue()	Gets the searchValue option's value.
searchValue(value)	Sets the searchValue option's value.
select()	Gets the select option's value.
select(expr)	Sets the select option's value.
sort()	Gets the sort option's value.
sort(sortExpr)	Sets the sort option's value.
store()	Gets 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.

Attach a handler for a DataSource event
Assign a callback function to the DataSource option that takes on a handler for the required event. The events that can be handled within the DataSource's configuration object are listed in the Configuration section. All these events have names starting with on.
Attach several handlers for one or several events to a DataSource
Specify event handling functions for one or more events using the on() method. All the DataSource events are listed in the Events section.