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 configuring a widget using ASP.NET MVC Wrappers, 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 using ASP.NET MVC Wrappers, 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	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.

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.