Methods

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

byKey(key)

Returns the data item specified by the key.

Parameters:
key:

Object

|

String

|

Number

Specifies the key value of the required items.

Return Value:

Promise<any> (jQuery or native)

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

The following example demonstrates how to get an item whose key property value equals 15.

JavaScript
store.byKey(15).done(function(dataItem) {
        // process 'dataItem'
    }).fail(function(error) {
        // handle error
    });

clearRawDataCache()

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

insert(values)

Adds an item to the data associated with this Store.

Parameters:
values:

Object

An object representing the new item.

Return Value:

Promise<any> (jQuery or native)

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

JavaScript
store.insert({
        id: 5,
        name: "item1",
        value: 10
    })
    .done(function(values, key) {
        //'values' contains the inserted item values
        //'key' contains the inserted item key
    })
    .fail(function(error) {
        //handle error
    });
NOTE
If data already contains an object with the same key property value as the object being inserted, the insertion fails.

key()

Returns the key expression specified via the key configuration option.

Return Value: any

A key expression or an array of key expressions.

If the Store contains only one key expression, the function returns this expression. If it contains several key expressions, the function returns an array of expressions.

keyOf(obj)

Returns the key of the Store item that matches the specified object.

Parameters:
obj:

Object

An object whose key value you need to get.

Return Value: any

The key value of the Store item that matches the specified object.

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

The object specifying data shaping options.

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.

JavaScript
store.load(options)
    .done(function(result) {
        // 'result' contains the loaded data
    })
    .fail(function(error) {
        // handle error
    })

For more information on data shaping options, refer to the Data Layer topic.

off(eventName)

Detaches all event handlers from the specified event.

Parameters:
eventName:

String

The name of the event to unsubscribe from.

Return Value:

Object

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

Parameters:
eventName:

String

The name of the event to unsubscribe from.

eventHandler:

function

The handler to be detached from the specified event.

Return Value:

Object

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to a specified event.

Parameters:
eventName:

String

The name of the event to be subscribed.

eventHandler:

function

An event handler for the specified event.

Return Value:

Object

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 the specified events.

Parameters:
events:

Object

An object of the following structure: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

Object

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

remove(key)

Removes the data item specified by the key.

Parameters:
key:

Object

|

String

|

Number

The data item key value.

Return Value:

Promise (jQuery or native)

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

JavaScript
store.remove(key)
    .done(function() {
        // handle success
    })
    .fail(function(error) {
        // handle error
    });

totalCount(options)

Obtains the total count of items that will be returned by the load() function.

Parameters:
obj:

Object

An object holding filtering and grouping options.

Object structure:
filter:

Object

Data filtering conditions.

group:

Object

Data grouping options.

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
myStore.totalCount(options)
    .done(function(result) {
        // 'result' contains the item count.
    })
    .fail(function(error) {
        // handle error
    });

For more information on filtering and grouping options, refer to the Filtering and Grouping sections of the Data Layer article.

update(key, values)

Updates the data item specified by the key.

Parameters:
key:

Object

|

String

|

Number

The key value of the item being updated.

values:

Object

The object containing new values for the specified item.

Return Value:

Promise<any> (jQuery or native)

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

JavaScript
store.update(key, values)
    .done(function(key, result) {
        // "key" contains the key of the updated item
        // "result" contains the updated item itself
    })
    .fail(function(error) {
        // handle error
    });