Configuration

This section describes configuration options used to configure the CustomStore.

byKey

The user implementation of the byKey(key, extraOptions) method.

Type: function
Function parameters:
The required key value.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the item has been loaded.

The method passed to this option should return either the jQuery.Deferred promise or the jQuery.Deferred compatible object.

JavaScript
var myStore = new DevExpress.data.CustomStore({
    byKey: function(key) {
        var d = new $.Deferred();
        $.get('http://data.example.com/products?id=' + key)
            .done(function (result) {
                d.resolve(result[i]);
            });
        return d.promise();
    },
    . . .
});

errorHandler

Specifies the function called when the Store causes an error.

Type: function

The function passed to this option takes on the JavaScript Error object as a parameter.

JavaScript
var storeConfig = {
    errorHandler: function(error) {
        console.log(error.message);
    }
};

insert

The user implementation of the insert(values) method.

Type: function
Function parameters:
values: Object
An object representing the inserted item.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the item has been inserted.

The method passed to this option should return either the jQuery.Deferred promise or the jQuery.Deferred compatible object.

You can resolve the returned jQuery.Deferred with any data. For example, the key of the inserted item.

JavaScript
var store = new DevExpress.data.CustomStore({
    insert: function (values) {
        var deferred = $.Deferred();
        $.post("http://www.example.com/service/myEntity", values).done(function(data) {
            deferred.resolve(data.key);
        })
        return deferred.promise();
    }
});

key

Specifies the key properties within the data associated with the Store.

Type: String|Array

The key configuration option is required if you create a Store for read-write data access. The key property is specified by an appropriate getter. If you need to specify a compound key property, assign an array of getters to this option.

The following example demonstrates how to set id and code key properties.

JavaScript
var storeConfig = {
    key: ["id", "code"]
}

load

The user implementation of the load(options) method.

Type: function
Function parameters:
options: Object
An object specifying data shaping options.
Object structure:
filter: Object
Filter expression.
sort: Object
Sort expression.
select: Object
Select expression.
group: Object
Group expression.
skip: Number
The index of the first loaded item.
take: Number
The number of loaded items.
userData: Object
A bag for holding user-defined parameters.
requireTotalCount: Boolean
Specifies whether the function passed to this option should resolve the jQuery.Deferred with the second argument containing the totalCount field.
Return Value: jQuery.Promise
A promise of a deferred object resolved after data is loaded.

The function passed to this option should return a promise. More often, this is either a jQuery.Deferred promise or a jQuery.Deferred compatible object.

NOTE: In AngularJS approach, APIs for deferred/promises are exposed by the $q service.

If the loadOptions.requireTotalCount field is true, the function should resolve the jQuery.Deferred with a second argument containing the totalCount field as shown in the following code snippet.

JavaScript
var store = new DevExpress.data.CustomStore({
    load: function (loadOptions) {
        var deferred = $.Deferred();
        $.get('url/to/the/resource', loadOptions).done(function (response) {
            if (loadOptions.requireTotalCount === true)
                deferred.resolve(response.data, { totalCount: response.totalCount });
            else
                deferred.resolve(response.data)
        });
        return deferred.promise();
    }
});

In AngularJS approach, if the loadOptions.requireTotalCount field is true, the promise must be resolved with an object of two fields: data and totalCount. In the following code snippet, the .then() method creates a promise internally and resolves it with the return from the callback function.

JavaScript
var store = new DevExpress.data.CustomStore({
    load: function (loadOptions) {
        return $http.get('url/to/the/resource', loadOptions).then(function (response) {
                    if (loadOptions.requireTotalCount === true)
                        return { data: response.data, totalCount: response.totalCount };
                    else
                        return response.data;
                })
    }
});

onInserted

A handler for the inserted event.

Type: function
Function parameters:
values: Object
An object representing the inserted item.
A key value of the inserted item.

Assign a function to perform a custom action after a data item is added.

onInserting

A handler for the inserting event.

Type: function
Function parameters:
values: Object
An object representing the item being inserted.

Assign a function to perform a custom action before a data item is added.

onLoaded

A handler for the loaded event.

Type: function
Function parameters:
result: Array
The loaded data array.

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

onLoading

A handler for the loading event.

Type: function
Function parameters:
loadOptions: Object
An object defining options for the loaded data.
Object structure:
filter: Object
A filter expression for the loaded data.
sort: Object
A sort expression for the loaded data.
select: Object
An expression for selection in the loaded data.
group: Object
An expression for grouping in the loaded data.
skip: Number
The number of item to skip.
take: Number
The number of items to take for the loaded data.
userData: Object
A bag for holding user-defined parameters.

Assign a function to perform a custom action before data is loaded.

onModified

A handler for the modified event.

Type: function

Assign a function to perform a custom action after data is modified.

onModifying

A handler for the modifying event.

Type: function

Assign a function to perform a custom action before the data is modified.

onRemoved

A handler for the removed event.

Type: function
Function parameters:
A key value of the removed item.

Assign a function to perform a custom action after a data item has been removed.

onRemoving

A handler for the removing event.

Type: function
Function parameters:
A key value of the item being removed.

Assign a function to perform a custom action before a data item is removed.

onUpdated

A handler for the updated event.

Type: function
Function parameters:
A key value of the updated item.
values: Object
New values for the updated item.

Assign a function to perform a custom action after a data item has been updated.

onUpdating

A handler for the updating event.

Type: function
Function parameters:
A key value of the item being updated.
values: Object
New values for the item being updated.

Assign a function to perform a custom action before a data item is updated.

remove

The user implementation of the remove(key) method.

Type: function
Function parameters:
The key value of the item being removed.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the item has been removed.

The method passed to this option should return either the jQuery.Deferred promise or jQuery.Deferred compatible object.

totalCount

The user implementation of the totalCount(options) method.

Type: function
Function parameters:
loadOptions: Object
An object specifying filtering and grouping options.
Object structure:
filter: Object
Data filtering conditions.
group: Object
Data grouping options.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after data has been loaded.

The method passed to this option should return either the jQuery.Deferred promise or jQuery.Deferred compatible object.

update

The user implementation of the update(key, values) method.

Type: function
Function parameters:
The key value of the item being updated.
values: Object
The object containing new values for the specified item.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the item has been updated.

The method passed to this option should return either the jQuery.Deferred promise or the jQuery.Deferred compatible object.

You can resolve the returned jQuery.Deferred with any data. For example, the key of the updated item.

JavaScript
var store = new DevExpress.data.CustomStore({
    update: function (key, values) {
        var deferred = $.Deferred();
        $.ajax({
            url: SERVICE_URL + "/" + encodeURIComponent(key),
            method: "PUT",
            data: values
        }).done(function(){
            deferred.resolve(key);
        });
        return deferred.promise();
    }
});

useDefaultSearch

Specifies whether or not the store combines the search expression with the filter expression.

Type: Boolean
Default Value: false