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

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.

filter

Specifies data filtering conditions.

For information on filter expressions, refer to the Filtering section of the Data Layer article.

To clear filtering conditions, assign null to the filter option.

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
The data array to be processed.
Return Value: Array
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 done callback of the Deferred.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

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

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

For more information on searching, refer to the Search Api section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

searchOperation

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

Type: String
Default Value: 'contains'

The option supports the following values: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".

For more information on searching, refer to the Search Api section of the Data Layer article.

searchValue

Specifies the value to which the search expression is compared.

Type: any
Default Value: null

For more information on searching, refer to the Search Api section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

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.

store

Specifies the underlying Store instance used to access data.

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.