DevExtreme jQuery - CustomStore API

The CustomStore enables you to implement custom data access logic for consuming data from any source.

import CustomStore from "devextreme/data/custom_store"

DevExtreme provides extensions for ASP.NET and PHP that configure the CustomStore and implement server-side data processing. A third-party extension is available for MongoDB. You can also implement the CustomStore manually.

The CustomStore's implementation depends on whether data is processed on the client or server. For client-side data processing, implement the load function to load data from the data source. Refer to the Load Data in the Raw Mode article for more information.

For server-side data processing, implement the load function to send data processing parameters to the server. The server should send back processed data. load and CustomStore have specifics that depend on the UI component that uses the CustomStore. Refer to the load description for more information.

If your data source supports CRUD operations, implement the insert, update, and remove functions.

The following code example uses CustomStore to specify CRUD operations for a component. For a more in-depth example, refer to the following article: Custom Data Sources.

jQuery

JavaScript

const store = new DevExpress.data.CustomStore({
    key: "id",
    load: function (loadOptions) {
        // ...
    },
    insert: function (values) {
        // ...
    },
    update: function (key, values) {
        // ...
    },
    remove: function (key) {
        // ...
    }
});

// ===== or inside the DataSource =====
const dataSource = new DevExpress.data.DataSource({
    // ...
    // a mix of CustomStore and DataSource properties
    // ...
});

Angular

TypeScript

import CustomStore from "devextreme/data/custom_store";
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    store: CustomStore;
    dataSource: DataSource;
    constructor () {
        this.store = new CustomStore({
            key: "id",
            load: (loadOptions) => {
                // ...
            },
            insert: (values) => {
                // ...
            },
            update: (key, values) => {
                // ...
            },
            remove: (key) => {
                // ...
            }
        });

        // ===== or inside the DataSource =====
        this.dataSource = new DataSource({
            // ...
            // a mix of CustomStore and DataSource properties
            // ...
        });
    }
}

Vue

App.vue

<script>
import CustomStore from 'devextreme/data/custom_store';
import DataSource from 'devextreme/data/data_source';

const store = new CustomStore({
    key: 'id',
    load: (loadOptions) => {
        // ...
    },
    insert: (values) => {
        // ...
    },
    update: (key, values) => {
        // ...
    },
    remove: (key) => {
        // ...
    }
});

// ===== or inside the DataSource =====
const dataSource = new DataSource({
    // ...
    // a mix of CustomStore and DataSource properties
    // ...
});

export default {
    // ...
    data() {
        return {
            store,
            // ===== or =====
            dataSource
        }
    }
}
</script>

React

App.js

// ...
import CustomStore from 'devextreme/data/custom_store';
import DataSource from 'devextreme/data/data_source';

const store = new CustomStore({
    key: 'id',
    load: (loadOptions) => {
        // ...
    },
    insert: (values) => {
        // ...
    },
    update: (key, values) => {
        // ...
    },
    remove: (key) => {
        // ...
    }
});

// ===== or inside the DataSource =====
const dataSource = new DataSource({
    // ...
    // a mix of CustomStore and DataSource properties
    // ...
});

function App() {
    // ...
}
export default App;

NOTE

The CustomStore is immutable. You cannot change its configuration at runtime. However, you can use its methods to manipulate it.

Options

This section describes properties that configure the CustomStore.

Name	Description
byKey	Specifies a custom implementation of the byKey(key) method.
cacheRawData	Specifies whether raw data should be saved in the cache. Applies only if loadMode is "raw".
errorHandler	Specifies the function that is executed when the store throws an error.
insert	Specifies a custom implementation of the insert(values) method.
key	Specifies the key property (or properties) that provide(s) key values to access data items. Each key value must be unique.
load	Specifies a custom implementation of the load(options) method.
loadMode	Specifies how data returned by the load function is treated.
onInserted	A function that is executed after a data item is added to the store.
onInserting	A function that is executed before a data item is added to the store.
onLoaded	A function that is executed after data is loaded to the store.
onLoading	A function that is executed before data is loaded to the store.
onModified	A function that is executed after a data item is added, updated, or removed from the store.
onModifying	A function that is executed before a data item is added, updated, or removed from the store.
onPush	The function executed before changes are pushed to the store.
onRemoved	A function that is executed after a data item is removed from the store.
onRemoving	A function that is executed before a data item is removed from the store.
onUpdated	A function that is executed after a data item is updated in the store.
onUpdating	A function that is executed before a data item is updated in the store.
remove	Specifies a custom implementation of the remove(key) method.
totalCount	Specifies a custom implementation of the totalCount(options) method.
update	Specifies a custom implementation of the update(key, values) method.
useDefaultSearch	Specifies whether the store combines the search and filter expressions. Defaults to true if the loadMode is "raw" and false if it is "processed".

Methods

This section describes the methods used to access data associated with the CustomStore.

Name	Description
byKey(key)	Gets a data item with a specific key.
clearRawDataCache()	Deletes data from the cache. Takes effect only if the cacheRawData property is true.
insert(values)	Adds a data item to the store.
key()	Gets the key property (or properties) as specified in the key property.
keyOf(obj)	Gets a data item's key value.
load()	Starts loading data.
load(options)	Starts loading data.
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.
push(changes)	Pushes data changes to the store and notifies the DataSource.
remove(key)	Removes a data item with a specific key from the store.
totalCount(options)	Gets the total count of items the load() function returns.
update(key, values)	Updates a data item with a specific key.

Events

This section describes events that the CustomStore raises.

Name	Description
inserted	Raised after a data item is added to the store.
inserting	Raised before a data item is added to the store.
loaded	Raised after data is loaded to the store.
loading	Raised before data is loaded to the store.
modified	Raised after a data item is added, updated, or removed from the store.
modifying	Raised before a data item is added, updated, or removed from the store.
push	Raised before changes are pushed to the store.
removed	Raised after a data item is removed from the store.
removing	Raised before a data item is removed from the store.
updated	Raised after a data item is updated in the store.
updating	Raised before a data item is updated in the store.

LoadOptions

This section describes the loadOptions object's fields.

Type:

Object

This object is used to specify settings according to which the server should process data. More often these settings are passed as a parameter to the load function and depend on the operations (paging, filtering, sorting, etc.) that you have enabled in the DataSource or UI component.