Configuration

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

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

customQueryParams

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

Type:

Object

You can use this option to pass additional parameters to OData service operations. Refer to the Data Layer guide for more information.

NOTE
This option makes sense only if the current DataSource instance is associated with an ODataStore.

expand

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

Type:

Array<String>

|

String

This option is specific to the data sources that use a data store of the ODataStore type.

To learn more on this option, refer to the Associations topic.

In an ASP.NET MVC Control, specify this option in the OData() data source:

Razor C#
Razor VB
@(Html.DevExtreme().WidgetName()
    .DataSource(ds => ds.OData()
        .Expand("PropertyName1", "PropertyName2")
    )
)
@(Html.DevExtreme().WidgetName() _
    .DataSource(Function(ds)
        Return ds.OData() _
                 .Expand("PropertyName1", "PropertyName2")
    End Function)
)

filter

Specifies data filtering conditions.

Setting this option to null clears filtering settings.

NOTE
Filtering works when inputting a plain data structure only. However, if you need the filtering capability and hierarchical data, transform the plain data using the DataSource's group option.
See Also

group

Specifies data grouping conditions.

For information on group expressions, refer to the Grouping section of the Data Layer article.

map

The item mapping function.

Type:

function

Function parameters:
dataItem:

Object

The data item to be processed.

Return Value:

Object

The processed data item.

For more information on item mapping, refer to the Item Mapping section of the Data Layer article.

onChanged

A handler for the changed event.

Type:

function

Assign a function to perform a custom action after data is successfully loaded.

onLoadError

A handler for the loadError event.

Type:

function

Function parameters:
error:

Object

An object defining the occurred error.

Object structure:
message:

String

The system message about the occurred error.

Assign a function to perform a custom action when data loading fails.

onLoadingChanged

A handler for the loadingChanged event.

Type:

function

Function parameters:
isLoading:

Boolean

Indicates whether data is being loaded.

Assign a function to perform a custom action when the data loading status is changed.

pageSize

Specifies the maximum number of items the page can contain.

Type:

Number

Default Value: 20
NOTE
If you specify the pageSize option value when the group option is true, set the paginate option to true as well. Otherwise, the DataSource instance loads all items at once ignoring the pageSize option.

paginate

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

Type:

Boolean

Default Value: undefined
NOTE
If the group option is disabled, the default value of the paginate option is true. Otherwise, false.

postProcess

The data post processing function.

Type:

function

Function parameters:
data:

Array<any>

The data array to be processed.

Return Value:

Array<any>

The processed data array.

For more information on post processing, refer to the Post Processing section of the Data Layer article.

requireTotalCount

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

Type:

Boolean

If this option is set to true, the callback of the Promise returned by the load() method will hold the extra argument containing the totalCount, which holds the total count of data source items.

searchExpr

Specifies a value by which the required items are searched.

Type:

getter

|

Array<getter>

In most cases, you should pass the name of a field by whose value data items are searched. Assign an array of field names to this option if you need to search elements by several field values.

JavaScript
var dataSource = new DevExpress.data.DataSource({
    store: myStore,
    searchExpr: ["firstName", "lastName"]
});

You can use this option along with searchOperation and searchValue to specify a simple filter. Use the filter option for more complex filtering conditions. Filters are combined if you specify them in both ways.

NOTE
Searching works when inputting a plain data structure only. However, if you need the searching capability and hierarchical data, transform the plain data using the DataSource's group option.
See Also

searchOperation

Specifies the comparison operation used to search for the required items. One of "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".

Type:

String

Default Value: 'contains'

You can use this option along with searchExpr and searchValue to specify a simple filter. Use the filter option for more complex filtering conditions. Filters are combined if you specify them in both ways.

In an ASP.NET MVC Control, specify this option using the FilterOperations enum that accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, NotContains, Contains, StartsWith, EndsWith and Between.

See Also

searchValue

Specifies the value to which the search expression is compared.

Type: any
Default Value: null

You can use this option along with searchExpr and searchOperation to specify a simple filter. Use the filter option for more complex filtering conditions. Filters are combined if you specify them in both ways.

See Also

select

Specifies the initial select option value.

For information on select expressions, refer to the Select Expressions section of the Data Layer article.

sort

Specifies the initial sort option value.

For information on sort expressions, refer to the Sorting section of the Data Layer article.

In an ASP.NET MVC Control, specify this option in the following manner:

Razor C#
Razor VB
@(Html.DevExtreme().WidgetName()
    .DataSourceOptions(dso => dso
        .Sort("Discount", false) // for a single sorting condition
        // === or ===
        .Sort(s => {             // for multiple sorting conditions
            s.AddSorting("LastName");
            s.AddSorting("Discount", false);
        })
    )
)
@(Html.DevExtreme().WidgetName() _
    .DataSourceOptions(Sub(dso)
        dso.Sort("Discount", False) ' for a single sorting condition
        ' === or ===
        dso.Sort(Sub(s)             ' for multiple sorting conditions
            s.AddSorting("LastName")
            s.AddSorting("Discount", False)
        End Sub)
    End Sub)
)

store

Specifies the underlying Store instance used to access data.

Type:

Store

|

Store configuration

|

Array<any>

| any

You can assign a Store instance or an array to this option. If you assign an array to the store option, the ArrayStore will automatically be created within the DataSource.