Print Friendly

Class Ext.data.Store

Package:Ext.data
Class:Store
Extends:Observable
Subclasses:JsonStore, 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.

A 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
Used to define events on this Observable
  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.
  collect( String dataIndex, [Boolean allowNull], [Boolean bypassFilter] ) : Array Store
Collects unique values for a particular dataIndex from this store.
  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 anyMatch ) : void 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( Number 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 which t...
  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 has any listeners for a specified event
  indexOf( Ext.data.Record record ) : 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 scope], [Object options] ) : void Observable
Appends an event handler to this element (shorthand for addListener)
  purgeListeners() : void Observable
Removes all listeners for this object
  query( String field, String/RegExp value, Boolean anyMatch ) : MixedCollection Store
Query the records by a specified property.
  queryBy( Function fn, [Object scope] ) : MixedCollection Store
Query by a function. The specified function will be called with each record in this data source. If the function retu...
  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...
  sum( String property, Number start, Number end ) : Number Store
Sums the value of property for each record between start and end and returns the result.
  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...
  metachange : ( Store this, Object meta ) Store
Fires when this stores reader provides new meta data (fields). This is currently only support for JsonReaders.
  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
  data : Array Store
Inline data to be loaded when the store is initialized.
  proxy : Ext.data.DataProxy Store
The Proxy object which provides access to a data object.
  pruneModifiedRecords : boolean Store
True to clear all modified record information each time the store is loaded or when a record is removed. (defaults to...
  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 )
Used to define events on this Observable
Parameters:
  • object : Object
    The object with the events defined
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.
    • 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) 

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

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

    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 which passes the same scope object to all handlers: 

    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.

collect

public function collect( String dataIndex, [Boolean allowNull], [Boolean bypassFilter] )
Collects unique values for a particular dataIndex from this store.
Parameters:
  • dataIndex : String
    The property to collect
  • allowNull : Boolean
    (optional) Pass true to allow null, undefined or empty string values
  • bypassFilter : Boolean
    (optional) Pass true to collect from all records, even ones which are filtered
Returns:
  • Array
    An array of the unique values
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, Boolean anyMatch )
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
  • anyMatch : Boolean
    True to match any part not just the beginning
Returns:
  • void
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( Number index )
Get the Record at the specified index.
Parameters:
  • index : Number
    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 has any listeners 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 record )
Get the index within the cache of the passed Record.
Parameters:
  • record : Ext.data.Record
    The Ext.data.Record object to to find.
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)
    • add {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 scope], [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
  • scope : Object
    (optional) The scope in which to execute the handler function. The handler function's "this" context.
  • 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.

query

public function query( String field, String/RegExp value, Boolean anyMatch )
Query 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
  • anyMatch : Boolean
    True to match any part not just the beginning
Returns:
  • MixedCollection
    Returns an Ext.util.MixedCollection of the matched records
This method is defined by Store.

queryBy

public function queryBy( Function fn, [Object scope] )
Query 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 in the results.
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:
  • MixedCollection
    Returns an Ext.util.MixedCollection of the matched records
This method is defined by Store.

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.

sum

public function sum( String property, Number start, Number end )
Sums the value of property for each record between start and end and returns the result.
Parameters:
  • property : String
    A field on your records
  • start : Number
    The record index to start at (defaults to 0)
  • end : Number
    The last record index to include (defaults to length - 1)
Returns:
  • Number
    The sum
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.

metachange

public event metachange
Fires when this stores reader provides new meta data (fields). This is currently only support for JsonReaders.
Subscribers will be called with the following parameters:
  • this : Store
  • meta : Object
    The JSON meta data
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.

data

data : Array
Inline data to be loaded when the store is initialized.
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.

pruneModifiedRecords

pruneModifiedRecords : boolean
True to clear all modified record information each time the store is loaded or when a record is removed. (defaults to false).
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.