DevExtreme jQuery - CustomStore Methods

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

byKey(key, extraOptions)

Gets a data item with a specific key.

Parameters:
key:

Object

|

String

|

Number

A data item's key value.

extraOptions:

LoadOptions

Data processing settings.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the data item is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

JavaScript
  • // The key consists of a single data field
  • var singleKeyStore = new DevExpress.data.CustomStore({
  • key: "field1",
  • // ...
  • });
  •  
  • // Gets the data item with "field1" being equal to 1
  • singleKeyStore.byKey(1)
  • .done(function (dataItem) {
  • // Process the "dataItem" here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });
  •  
  • // The key consists of several data fields
  • var compositeKeyStore = new DevExpress.data.CustomStore({
  • key: [ "field1", "field2" ],
  • // ...
  • });
  •  
  • // Gets the data item with both "field1" and "field2" being equal to 1
  • compositeKeyStore.byKey({
  • field1: 1,
  • field2: 1
  • }).done(function (dataItem) {
  • // Process the "dataItem" here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });

clearRawDataCache()

Deletes data from the cache. Takes effect only if the cacheRawData property is true.

  • var store = new DevExpress.data.CustomStore({
  • // CustomStore is configured here
  • cacheRawData: true
  • });
  •  
  • store.clearRawDataCache();

insert(values)

Adds a data item to the store.

Parameters:
values:

Object

A data item.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after a data item is added. It is a native Promise or a jQuery.Promise when you use jQuery.

In the following code, dataObj is a data object added to the database and returned from the server. If the server returns nothing or the store works with local data, dataObj contains the data object passed to the insert method.

JavaScript
  • var store = new DevExpress.data.CustomStore({
  • // CustomStore is configured here
  • });
  •  
  • store.insert({ id: 1, name: "John Doe" })
  • .done(function (dataObj, key) {
  • // Process the key and data object here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });
NOTE
The data item's key value should be unique, otherwise, the insertion will fail.

key()

Gets the key property (or properties) as specified in the key property.

Return Value:

String

|

Array<String>

The key property's value.

JavaScript
  • var store = new DevExpress.data.CustomStore({
  • // ...
  • key: "ProductID"
  • });
  •  
  • var keyProps = store.key(); // returns "ProductID"

keyOf(obj)

Gets a data item's key value.

Parameters:
obj:

Object

A data item.

Return Value: any |

String

|

Number

The data item's key value.

JavaScript
  • var store = new DevExpress.data.CustomStore({
  • // ...
  • key: "id"
  • });
  •  
  • var key = store.keyOf({ id: 1, name: "John Doe" }); // returns 1

load()

Starts loading data.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

load(options)

Starts loading data.

Parameters:
options:

LoadOptions

Data processing settings.

Return Value:

Promise<LoadResult> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

JavaScript
  • const store = new DevExpress.data.CustomStore({
  • // CustomStore is configured here
  • });
  •  
  • store.load(options)
  • .done(function (data) {
  • // Process "data" here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });

off(eventName)

Detaches all event handlers from a single event.

Parameters:
eventName:

String

The event's name.

Return Value:

CustomStore

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from a single event.

Parameters:
eventName:

String

The event's name.

eventHandler:

Function

The event's handler.

Return Value:

CustomStore

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to an event.

Parameters:
eventName:

String

The event's name.

eventHandler:

Function

The event's handler.

Return Value:

CustomStore

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

See Also

on(events)

Subscribes to events.

Parameters:
events:

Object

Events with their handlers: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

CustomStore

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

push(changes)

Pushes data changes to the store and notifies the DataSource.

Parameters:
changes:

Array<any>

Data changes to be pushed.

Each data change is an object that can have the following fields:

  • type: String
    Data change type: "insert", "update", or "remove".

  • data: Object
    Changes that should be applied to the store's data.

  • key: any
    The key of the data item being updated or removed.

  • index: Number
    The position at which to display a new data item in a UI component bound to the store. To display the new data item first, set the index to 0. To add it to the end of the current page, set the index to -1.

    The index field is optional. If you do not specify it, the new data item is added to the end of the dataset. However, if data is grouped or split into pages, this item does not appear in the UI component until data is reshaped. In this case, specify the index to show the pushed item immediately.

    The index field is ignored if reshapeOnPush is enabled (see the note below).

The following code shows how to use the push(changes) method for each change type:

JavaScript
  • var store = new DevExpress.data.CustomStore({
  • // CustomStore is configured here
  • });
  •  
  • store.push([{ type: "insert", data: dataObj, index: index }]);
  • store.push([{ type: "update", data: dataObj, key: key }]);
  • store.push([{ type: "remove", key: key }]);
NOTE
  • The DataSource does not automatically sort, group, filter, or otherwise shape pushed data. For this reason, the DataSource and the UI component bound to it can be out of sync. To prevent this, enable the reshapeOnPush property. We also recommend specifying the pushAggregationTimeout property to reduce the number of updates and recalculations.
  • The push method does not raise data source modification events (for instance, onInserted, onRemoved, onUpdated). Handle the onPush event to perform actions when data changes are pushed to a store.
  • The push method does not modify the remote data source. It is used to push changes from the data source to the local store without reloading data.

DataGrid Real-Time Updates Demo DataGrid SignalR Demo Chart SignalR Demo DataGrid Collaborative Editing Demo

View on GitHub

See Also

remove(key)

Removes a data item with a specific key from the store.

Parameters:
key:

Object

|

String

|

Number

A data item's key value.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the data item is removed. It is a native Promise or a jQuery.Promise when you use jQuery.

JavaScript
  • // The key consists of a single data field
  • var singleKeyStore = new DevExpress.data.CustomStore({
  • key: "field1",
  • // ...
  • });
  •  
  • // Removes the data item with "field1" being equal to 1
  • singleKeyStore.remove(1)
  • .done(function (key) {
  • // Process the "key" here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });
  •  
  • // The key consists of several data fields
  • var compositeKeyStore = new DevExpress.data.CustomStore({
  • key: [ "field1", "field2" ],
  • // ...
  • });
  •  
  • // Removes the data item with both "field1" and "field2" being equal to 1
  • compositeKeyStore.remove({
  • field1: 1,
  • field2: 1
  • }).done(function (key) {
  • // Process the "key" here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });

totalCount(options)

Gets the total count of items the load() function returns.

Parameters:
obj:

Object

Filtering and grouping properties.

Object structure:
Name Type Description
filter

Object

A filtering expression; described in the Filtering section.

group

Object

A grouping expression; described in the Grouping section.

Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the total item count is obtained. It is a native Promise or a jQuery.Promise when you use jQuery.

JavaScript
  • var store = new DevExpress.data.CustomStore({
  • // CustomStore is configured here
  • });
  •  
  • store.totalCount()
  • .done(function (count) {
  • // Process the "count" here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });

update(key, values)

Updates a data item with a specific key.

Parameters:
key:

Object

|

String

|

Number

A data item's key value.

values:

Object

An object with new values for the data item.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the data item is updated. It is a native Promise or a jQuery.Promise when you use jQuery.

In the following code, dataObj is a data object updated in the database and returned from the server. If the server returns nothing or the store works with local data, dataObj contains the data object passed to the update method.

JavaScript
  • // The key consists of a single data field
  • var singleKeyStore = new DevExpress.data.CustomStore({
  • key: "field1",
  • // ...
  • });
  •  
  • // Updates the data item with "field1" being equal to 1
  • singleKeyStore.update(1, { name: "John Smith" })
  • .done(function (dataObj, key) {
  • // Process the key and data object here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });
  •  
  • // The key consists of several data fields
  • var compositeKeyStore = new DevExpress.data.CustomStore({
  • key: [ "field1", "field2" ],
  • // ...
  • });
  •  
  • // Updates the data item with both "field1" and "field2" being equal to 1
  • compositeKeyStore.update(
  • { field1: 1, field2: 1 },
  • { name: "John Smith" }
  • ).done(function (dataObj, key) {
  • // Process the key and data object here
  • })
  • .fail(function (error) {
  • // Handle the "error" here
  • });