Methods

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

byKey(key)

Returns the data item specified by the key.

Parameters:

Specifies the key value of the required items.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the item has been loaded.

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
    });

clear()

Removes all data associated with this Store.

JavaScript
store.clear();

createQuery()

Creates the Query object for the underlying array.

Return Value: Object

The desired Query object.

This method is used internally by the ArrayStore, but you can also use it for advanced queries.

JavaScript
var query = myStore.createQuery();

For more information on Queries, refer to the Data Layer article.

insert(values)

Adds an item to the data associated with this Store.

Parameters:
values: Object

An object representing the new item.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the item has been inserted.

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(options)

Starts loading data.

Parameters:
obj: Object

The object specifying data shaping options.

Object structure:
filter: Object

Data filtering conditions.

sort: Object

Data sorting options.

select: Object

Data selection options.

group: Object

Data grouping options.

skip: Number

The count of items to be excluded from loading.

take: Number

The count of items to be loaded.

userData: Object

A bag holding user-defined parameters.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after data has been loaded.

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.

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.

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 at one method call. Available events are listed in the Events section.

See Also

remove(key)

Removes the data item specified by the key.

Parameters:

The data item key value.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the item has been removed.

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: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the total item count is obtained.

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:

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.

JavaScript
store.update(key, values)
    .done(function(result) {
        // 'result' is an object containing the updated item key and values passed to the update method.
    })
    .fail(function(error) {
        // handle error
    });