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
Export: default
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.

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.