Print Friendly

# Class Ext.data.Store

Package: | Ext.data
Class: | Store
Extends: | Observable
Subclasses: | SimpleStore
Defined In: | Store.js

The Store class encapsulates a client side cache of Ext.data.Record objects which provide input data for widgets such as the Ext.grid.Grid, or the Ext.form.ComboBox. A Store object uses an implementation of Ext.data.DataProxy to access a data object unless you call loadData() directly and pass in your data. The Store object has no knowledge of the format of the data returned by the Proxy. The Store object uses its configured implementation of Ext.data.DataReader to create Ext.data.Record instances from the data object. These records are cached and made available through accessor functions.
Properties - Methods - Events - Config Options

## Public Properties

This class has no public properties.

## Public Methods

Method | Defined By
--- | ---
| Store(`Object config`) | Store
Creates a new Store
| add(`Ext.data.Record[] records`) : void | Store
Add Records to the Store and fires the add event.
| addEvents(`Object object`) : void | Observable
Copies any events from the passed object onto this object if they do not already exist. The passed object must also ...
| addListener(`String eventName`, `Function handler`, [`Object scope`], [`Object options`]) : void | Observable
Appends an event handler to this component
| clearFilter(`Boolean suppressEvent`) : void | Store
Revert to a view of the Record cache with no filtering applied.
| commitChanges() : void | Store
Commit all Records with outstanding changes. To handle updates for changes, subscribe to the Store's "update" event, ...
| each(`Function fn`, [`Object scope`]) : void | Store
Calls the specified function for each of the Records in the cache.
| filter(`String field`, `String/RegExp value`) : Boolean | Store
Filter the records by a specified property.
| filterBy(`Function fn`, [`Object scope`]) : void | Store
Filter by a function. The specified function will be called with each record in this data source. If the function ret...
| fireEvent(`String eventName`, `Object... args`) : Boolean | Observable
Fires the specified event with the passed parameters (minus the event name).
| getAt(`String index`) : Ext.data.Record | Store
Get the Record at the specified index.
| getById(`String id`) : Ext.data.Record | Store
Get the Record with the specified id.
| getCount() : void | Store
Gets the number of cached records. If using paging, this may not be the total size of the dataset. If the data objec...
| getModifiedRecords() : Ext.data.Record[] | Store
Get all records modified since the last load, or since the last commit.
| getRange([`Number startIndex`], [`Number endIndex`]) : Ext.data.Record[] | Store
Returns a range of Records between specified indices.
| getSortState() : void | Store
Returns the sort state of the Store as an object with two properties: field {String} The name of the field by whic...
| getTotalCount() : void | Store
Gets the total number of records in the dataset. If using paging, for this to be accurate, the data object used by t...
| hasListener(`String eventName`) : Boolean | Observable
Checks to see if this object is currently listening for a specified event
| indexOf(`Ext.data.Record[] records`) : Number | Store
Get the index within the cache of the passed Record.
| indexOfId(`String id`) : Number | Store
Get the index within the cache of the Record with the passed id.
| insert(`Number index`, `Ext.data.Record[] records`) : void | Store
Inserts Records to the Store at the given index and fires the add event.
| load(`Object options`) : void | Store
Loads the Record cache from the configured Proxy using the configured Reader. If using remote paging, then the first...
| loadData(`Object data`, [`Boolean append`]) : void | Store
Loads data from a passed data block. A Reader which understands the format of the data must have been configured in t...
| on(`String eventName`, `Function handler`, [`Object options`]) : void | Observable
Appends an event handler to this element (shorthand for addListener)
| purgeListeners() : void | Observable
Removes all listeners for this object
| rejectChanges() : void | Store
Cancel outstanding changes on all changed records.
| reload([`Object options`]) : void | Store
Reloads the Record cache from the configured Proxy using the configured Reader and the options from the last load ope...
| remove(`Ext.data.Record record`) : void | Store
Remove a Record from the Store and fires the remove event.
| removeAll() : void | Store
Remove all Records from the Store and fires the clear event.
| removeListener(`String eventName`, `Function handler`, [`Object scope`]) : void | Observable
Removes a listener
| setDefaultSort(`String fieldName`, [`String dir`]) : void | Store
Sets the default sort column and order to be used by the next load operation.
| sort(`String fieldName`, [`String dir`]) : void | Store
Sort the Records. If remote sorting is used, the sort is performed on the server, and the cache is reloaded. If local...
| un(`String eventName`, `Function handler`, [`Object scope`]) : void | Observable
Removes a listener (shorthand for removeListener)

## Public Events

Event | Defined By
--- | ---
| add : (`Store this`, `Ext.data.Record[] records`, `Number index`) | Store
Fires when Records have been added to the Store
| beforeload : (`Store this`, `Object options`) | Store
Fires before a request is made for a new data object. If the beforeload handler returns false the load action will b...
| clear : (`Store this`) | Store
Fires when the data cache has been cleared.
| datachanged : (`Store this`) | Store
Fires when the data cache has changed, and a widget which is using this Store as a Record cache should refresh its view.
| load : (`Store this`, `Ext.data.Record[] records`, `Object options`) | Store
Fires after a new set of Records has been loaded.
| loadexception : () | Store
Fires if an exception occurs in the Proxy during loading. Called with the signature of the Proxy's "loadexception" ev...
| remove : (`Store this`, `Ext.data.Record record`, `Number index`) | Store
Fires when Records have been removed from the Store
| update : (`Store this`, `Ext.data.Record record`, `String operation`) | Store
Fires when Records have been updated

## Config Options

Config Options | Defined By
--- | ---
| baseParams : Object | Store
An object containing properties which are to be sent as parameters on any HTTP request
| proxy : Ext.data.DataProxy | Store
The Proxy object which provides access to a data object.
| reader : Ext.data.Reader | Store
The Reader object which processes the data object and returns an Array of Ext.data.record objects which are cached ke...
| remoteSort : boolean | Store
True if sorting is to be handled by requesting the Proxy to provide a refreshed version of the data object in sorted ...
| sortInfo : Object | Store
A config object in the format: {field: "fieldName", direction: "ASC|DESC"}

## Constructor Details

### Store

`public function Store(`Object config`)`
Creates a new Store
Parameters:

- `config` : Object
  A config object containing the objects needed for the Store to access data, and read the data into Records.

## Method Details

### add

`public function add(`Ext.data.Record[] records`)`
Add Records to the Store and fires the add event.
Parameters:

- `records` : Ext.data.Record[]
  An Array of Ext.data.Record objects to add to the cache.

Returns:

- `void`

This method is defined by Store.

### addEvents

`public function addEvents(`Object object`)`
Copies any events from the passed object onto this object if they do not already exist. The passed object must also inherit from Observable for this method to have any effect.
Parameters:

- `object` : Object
  The object from which to copy events

Returns:

- `void`

This method is defined by Observable.

### addListener

`public function addListener(`String eventName`, `Function handler`, [`Object scope`], [`Object options`])`
Appends an event handler to this component
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `scope` : Object
  (optional) The scope in which to execute the handler function. The handler function's "this" context.
- `options` : Object
  (optional) An object containing handler configuration properties. This may contain any of the following properties:
  - scope {Object} The scope in which to execute the handler function. The handler function's "this" context.
  - delegate {String} A simple selector to filter the target or look for a descendant of the target
  - stopEvent {Boolean} True to stop the event. That is stop propagation, and prevent the default action.
  - preventDefault {Boolean} True to prevent the default action
  - stopPropagation {Boolean} True to prevent event propagation
  - normalized {Boolean} False to pass a browser event to the handler function instead of an Ext.EventObject
  - delay {Number} The number of milliseconds to delay the invocation of the handler after te event fires.
  - single {Boolean} True to add a handler to handle just the next firing of the event, and then remove itself.
  - buffer {Number} Causes the handler to be scheduled to run in an Ext.util.DelayedTask delayed by the specified number of milliseconds. If the event fires again within that time, the original handler is not invoked, but the new handler is scheduled in its place.

  Combining Options
  Using the options argument, it is possible to combine different types of listeners:
  A normalized, delayed, one-time listener that auto stops the event and passes a custom argument (forumId)

  Code:

      el.on('click', this.onClick, this, { single: true, delay: 100, stopEvent : true, forumId: 4 });

  The method also allows for a single argument to be passed which is a config object containing properties which specify multiple handlers.

  Attaching multiple handlers in 1 call
  Code:

      el.on({ 'click' : { fn: this.onClick scope: this, delay: 100 }, 'mouseover' : { fn: this.onMouseOver scope: this }, 'mouseout' : { fn: this.onMouseOut scope: this } });

  Or a shorthand syntax:
  Code:

      el.on({ 'click' : this.onClick, 'mouseover' : this.onMouseOver, 'mouseout' : this.onMouseOut scope: this });

Returns:

- `void`

This method is defined by Observable.

### clearFilter

`public function clearFilter(`Boolean suppressEvent`)`
Revert to a view of the Record cache with no filtering applied.
Parameters:

- `suppressEvent` : Boolean
  If true the filter is cleared silently without notifying listeners

Returns:

- `void`

This method is defined by Store.

### commitChanges

`public function commitChanges()`
Commit all Records with outstanding changes. To handle updates for changes, subscribe to the Store's "update" event, and perform updating when the third parameter is Ext.data.Record.COMMIT.
Parameters:

- None.

Returns:

- `void`

This method is defined by Store.

### each

`public function each(`Function fn`, [`Object scope`])`
Calls the specified function for each of the Records in the cache.
Parameters:

- `fn` : Function
  The function to call. The Record is passed as the first parameter. Returning false aborts and exits the iteration.
- `scope` : Object
  (optional) The scope in which to call the function (defaults to the Record).

Returns:

- `void`

This method is defined by Store.

### filter

`public function filter(`String field`, `String/RegExp value`)`
Filter the records by a specified property.
Parameters:

- `field` : String
  A field on your records
- `value` : String/RegExp
  Either a string that the field should start with or a RegExp to test against the field

Returns:

- `Boolean`
  True if the filter matched at least one record, else false

This method is defined by Store.

### filterBy

`public function filterBy(`Function fn`, [`Object scope`])`
Filter by a function. The specified function will be called with each record in this data source. If the function returns true the record is included, otherwise it is filtered.
Parameters:

- `fn` : Function
  The function to be called, it will receive 2 args (record, id)
- `scope` : Object
  (optional) The scope of the function (defaults to this)

Returns:

- `void`

This method is defined by Store.

### fireEvent

`public function fireEvent(`String eventName`, `Object... args`)`
Fires the specified event with the passed parameters (minus the event name).
Parameters:

- `eventName` : String
- `args` : Object...
  Variable number of parameters are passed to handlers

Returns:

- `Boolean`
  returns false if any of the handlers return false otherwise it returns true

This method is defined by Observable.

### getAt

`public function getAt(`String index`)`
Get the Record at the specified index.
Parameters:

- `index` : String
  The index of the Record to find.

Returns:

- `Ext.data.Record`
  The Record at the passed index. Returns undefined if not found.

This method is defined by Store.

### getById

`public function getById(`String id`)`
Get the Record with the specified id.
Parameters:

- `id` : String
  The id of the Record to find.

Returns:

- `Ext.data.Record`
  The Record with the passed id. Returns undefined if not found.

This method is defined by Store.

### getCount

`public function getCount()`
Gets the number of cached records.

If using paging, this may not be the total size of the dataset. If the data object used by the Reader contains the dataset size, then the getTotalCount() function returns the data set size

Parameters:

- None.

Returns:

- `void`

This method is defined by Store.

### getModifiedRecords

`public function getModifiedRecords()`
Get all records modified since the last load, or since the last commit.
Parameters:

- None.

Returns:

- `Ext.data.Record[]`
  An array of Records containing outstanding modifications.

This method is defined by Store.

### getRange

`public function getRange([`Number startIndex`], [`Number endIndex`])`
Returns a range of Records between specified indices.
Parameters:

- `startIndex` : Number
  (optional) The starting index (defaults to 0)
- `endIndex` : Number
  (optional) The ending index (defaults to the last Record in the Store)

Returns:

- `Ext.data.Record[]`
  An array of Records

This method is defined by Store.

### getSortState

`public function getSortState()`
Returns the sort state of the Store as an object with two properties:

     field {String} The name of the field by which the Records are sorted
     direction {String} The sort order, "ASC" or "DESC"

Parameters:

- None.

Returns:

- `void`

This method is defined by Store.

### getTotalCount

`public function getTotalCount()`
Gets the total number of records in the dataset.

If using paging, for this to be accurate, the data object used by the Reader must contain the dataset size

Parameters:

- None.

Returns:

- `void`

This method is defined by Store.

### hasListener

`public function hasListener(`String eventName`)`
Checks to see if this object is currently listening for a specified event
Parameters:

- `eventName` : String
  The name of the event to check for

Returns:

- `Boolean`
  True if the event is being listened for, else false

This method is defined by Observable.

### indexOf

`public function indexOf(`Ext.data.Record[] records`)`
Get the index within the cache of the passed Record.
Parameters:

- `records` : Ext.data.Record[]
  An Array of Ext.data.Record objects to add to the cache.

Returns:

- `Number`
  The index of the passed Record. Returns -1 if not found.

This method is defined by Store.

### indexOfId

`public function indexOfId(`String id`)`
Get the index within the cache of the Record with the passed id.
Parameters:

- `id` : String
  The id of the Record to find.

Returns:

- `Number`
  The index of the Record. Returns -1 if not found.

This method is defined by Store.

### insert

`public function insert(`Number index`, `Ext.data.Record[] records`)`
Inserts Records to the Store at the given index and fires the add event.
Parameters:

- `index` : Number
  The start index at which to insert the passed Records.
- `records` : Ext.data.Record[]
  An Array of Ext.data.Record objects to add to the cache.

Returns:

- `void`

This method is defined by Store.

### load

`public function load(`Object options`)`
Loads the Record cache from the configured Proxy using the configured Reader.

If using remote paging, then the first load call must specify the start and limit properties in the options.params property to establish the initial position within the dataset, and the number of Records to cache on each read from the Proxy.

It is important to note that for remote data sources, loading is asynchronous, and this call will return before the new data has been loaded. Perform any post-processing in a callback function, or in a "load" event handler.

Parameters:

- `options` : Object
  An object containing properties which control loading options:

       params {Object} An object containing properties to pass as HTTP parameters to a remote data source. callback {Function} A function to be called after the Records have been loaded. The callback is passed the following arguments: r : Ext.data.Record[] options: Options object from the load call success: Boolean success indicator scope {Object} Scope with which to call the callback (defaults to the Store object) append {Boolean} indicator to append loaded records rather than replace the current cache.

Returns:

- `void`

This method is defined by Store.

### loadData

`public function loadData(`Object data`, [`Boolean append`])`
Loads data from a passed data block. A Reader which understands the format of the data must have been configured in the constructor.
Parameters:

- `data` : Object
  The data block from which to read the Records. The format of the data expected is dependent on the type of Reader that is configured and should correspond to that Reader's readRecords parameter.
- `append` : Boolean
  (Optional) True to append the new Records rather than replace the existing cache.

Returns:

- `void`

This method is defined by Store.

### on

`public function on(`String eventName`, `Function handler`, [`Object options`])`
Appends an event handler to this element (shorthand for addListener)
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `options` : Object
  (optional)

Returns:

- `void`

This method is defined by Observable.

### purgeListeners

`public function purgeListeners()`
Removes all listeners for this object
Parameters:

- None.

Returns:

- `void`

This method is defined by Observable.

### rejectChanges

`public function rejectChanges()`
Cancel outstanding changes on all changed records.
Parameters:

- None.

Returns:

- `void`

This method is defined by Store.

### reload

`public function reload([`Object options`])`
Reloads the Record cache from the configured Proxy using the configured Reader and the options from the last load operation performed.
Parameters:

- `options` : Object
  (optional) An object containing properties which may override the options used in the last load operation. See load for details (defaults to null, in which case the most recently used options are reused).

Returns:

- `void`

This method is defined by Store.

### remove

`public function remove(`Ext.data.Record record`)`
Remove a Record from the Store and fires the remove event.
Parameters:

- `record` : Ext.data.Record
  Th Ext.data.Record object to remove from the cache.

Returns:

- `void`

This method is defined by Store.

### removeAll

`public function removeAll()`
Remove all Records from the Store and fires the clear event.
Parameters:

- None.

Returns:

- `void`

This method is defined by Store.

### removeListener

`public function removeListener(`String eventName`, `Function handler`, [`Object scope`])`
Removes a listener
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

### setDefaultSort

`public function setDefaultSort(`String fieldName`, [`String dir`])`
Sets the default sort column and order to be used by the next load operation.
Parameters:

- `fieldName` : String
  The name of the field to sort by.
- `dir` : String
  (optional) The sort order, "ASC" or "DESC" (defaults to "ASC")

Returns:

- `void`

This method is defined by Store.

### sort

`public function sort(`String fieldName`, [`String dir`])`
Sort the Records. If remote sorting is used, the sort is performed on the server, and the cache is reloaded. If local sorting is used, the cache is sorted internally.
Parameters:

- `fieldName` : String
  The name of the field to sort by.
- `dir` : String
  (optional) The sort order, "ASC" or "DESC" (defaults to "ASC")

Returns:

- `void`

This method is defined by Store.

### un

`public function un(`String eventName`, `Function handler`, [`Object scope`])`
Removes a listener (shorthand for removeListener)
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

## Event Details

### add

`public event add`
Fires when Records have been added to the Store
Subscribers will be called with the following parameters:

- `this` : Store
- `records` : Ext.data.Record[]
  The array of Records added
- `index` : Number
  The index at which the record(s) were added

This event is defined by Store.

### beforeload

`public event beforeload`
Fires before a request is made for a new data object. If the beforeload handler returns false the load action will be canceled.
Subscribers will be called with the following parameters:

- `this` : Store
- `options` : Object
  The loading options that were specified (see load for details)

This event is defined by Store.

### clear

`public event clear`
Fires when the data cache has been cleared.
Subscribers will be called with the following parameters:

- `this` : Store

This event is defined by Store.

### datachanged

`public event datachanged`
Fires when the data cache has changed, and a widget which is using this Store as a Record cache should refresh its view.
Subscribers will be called with the following parameters:

- `this` : Store

This event is defined by Store.

### load

`public event load`
Fires after a new set of Records has been loaded.
Subscribers will be called with the following parameters:

- `this` : Store
- `records` : Ext.data.Record[]
  The Records that were loaded
- `options` : Object
  The loading options that were specified (see load for details)

This event is defined by Store.

### loadexception

`public event loadexception`
Fires if an exception occurs in the Proxy during loading. Called with the signature of the Proxy's "loadexception" event.
Subscribers will be called with the following parameters:

- None.

This event is defined by Store.

### remove

`public event remove`
Fires when Records have been removed from the Store
Subscribers will be called with the following parameters:

- `this` : Store
- `record` : Ext.data.Record
  The Record that was removed
- `index` : Number
  The index at which the record was removed

This event is defined by Store.

### update

`public event update`
Fires when Records have been updated
Subscribers will be called with the following parameters:

- `this` : Store
- `record` : Ext.data.Record
  The Record that was updated
- `operation` : String
  The update operation being performed. Value may be one of:

       Ext.data.Record.EDIT Ext.data.Record.REJECT Ext.data.Record.COMMIT

This event is defined by Store.

## Config Details

### baseParams

`baseParams : Object`
An object containing properties which are to be sent as parameters on any HTTP request
This config option is defined by Store.

### proxy

`proxy : Ext.data.DataProxy`
The Proxy object which provides access to a data object.
This config option is defined by Store.

### reader

`reader : Ext.data.Reader`
The Reader object which processes the data object and returns an Array of Ext.data.record objects which are cached keyed by their id property.
This config option is defined by Store.

### remoteSort

`remoteSort : boolean`
True if sorting is to be handled by requesting the Proxy to provide a refreshed version of the data object in sorted order, as opposed to sorting the Record cache in place (defaults to false).
This config option is defined by Store.

### sortInfo

`sortInfo : Object`
A config object in the format: {field: "fieldName", direction: "ASC|DESC"}
This config option is defined by Store.

Ext - Copyright © 2006-2007 Ext JS, LLC
All rights reserved.