Clear Up
SharpKit Reference

Store Class

The Store class encapsulates a client side cache of Model objects. Stores load data via a Proxy, and also provide functions for sorting, filtering and querying the model instances contained within it.

Creating a Store is easy - we just tell it the Model and the Proxy to use to load and save its data:

  
// Set up a model to use in our Store
           Ext.define('User', {
           extend: 'Ext.data.Model',
           fields: [
           {name: 'firstName', type: 'string'},
           {name: 'lastName',  type: 'string'},
           {name: 'age',       type: 'int'},
           {name: 'eyeColor',  type: 'string'}
           ]
           });
           var myStore = Ext.create('Ext.data.Store', {
           model: 'User',
           proxy: {
           type: 'ajax',
           url: '/users.json',
           reader: {
           type: 'json',
           root: 'users'
           }
           },
           autoLoad: true
           });
            

In the example above we configured an AJAX proxy to load data from the url '/users.json'. We told our Proxy to use a JsonReader to parse the response from the server into Model object - see the docs on JsonReader for details.

Inline data

Stores can also load data inline. Internally, Store converts each of the objects we pass in as data into Model instances:

  
    Ext.create('Ext.data.Store', {
            model: 'User',
            data : [
            {firstName: 'Ed',    lastName: 'Spencer'},
            {firstName: 'Tommy', lastName: 'Maintz'},
            {firstName: 'Aaron', lastName: 'Conran'},
            {firstName: 'Jamie', lastName: 'Avins'}
            ]
            });
            

Loading inline data using the method above is great if the data is in the correct format already (e.g. it doesn't need to be processed by a reader). If your inline data requires processing to decode the data structure, use a MemoryProxy instead (see the MemoryProxy docs for an example).

Additional data can also be loaded locally using add.

Dynamic Loading

Stores can be dynamically updated by calling the load method:

  
store.load({
            params: {
            group: 3,
            type: 'user'
            },
            callback: function(records, operation, success) {
            // do something after the load finishes
            },
            scope: this
            });
            

Here a bunch of arbitrary parameters is passed along with the load request and a callback function is set up to do something after the loading is over.

Loading Nested Data

Applications often need to load sets of associated data - for example a CRM system might load a User and her Orders. Instead of issuing an AJAX request for the User and a series of additional AJAX requests for each Order, we can load a nested dataset and allow the Reader to automatically populate the associated models. Below is a brief example, see the Ext.data.reader.Reader intro docs for a full explanation:

  
var store = Ext.create('Ext.data.Store', {
           autoLoad: true,
           model: "User",
           proxy: {
           type: 'ajax',
           url: 'users.json',
           reader: {
           type: 'json',
           root: 'users'
           }
           }
           });
            

Which would consume a response like this:

  
{
           "users": [{
           "id": 1,
           "name": "Ed",
           "orders": [{
           "id": 10,
           "total": 10.76,
           "status": "invoiced"
           },{
           "id": 11,
           "total": 13.45,
           "status": "shipped"
           }]
           }]
           }
            

See the Ext.data.reader.Reader intro docs for a full explanation.

Filtering and Sorting

Stores can be sorted and filtered - in both cases either remotely or locally. The sorters and filters are held inside MixedCollection instances to make them easy to manage. Usually it is sufficient to either just specify sorters and filters in the Store configuration or call sort or filter:

  
var store = Ext.create('Ext.data.Store', {
           model: 'User',
           sorters: [{
           property: 'age',
           direction: 'DESC'
           }, {
           property: 'firstName',
           direction: 'ASC'
           }],
           filters: [{
           property: 'firstName',
           value: /Ed/
           }]
           });
            

The new Store will keep the configured sorters and filters in the MixedCollection instances mentioned above. By default, sorting and filtering are both performed locally by the Store - see remoteSort and remoteFilter to allow the server to perform these operations instead.

Filtering and sorting after the Store has been instantiated is also easy. Calling filter adds another filter to the Store and automatically filters the dataset (calling filter with no arguments simply re-applies all existing filters). Note that by default sortOnFilter is set to true, which means that your sorters are automatically reapplied if using local sorting.

  
store.filter('eyeColor', 'Brown');
            

Change the sorting at any time by calling sort:

  
store.sort('height', 'ASC');
            

Note that all existing sorters will be removed in favor of the new sorter data (if sort is called with no arguments, the existing sorters are just reapplied instead of being removed). To keep existing sorters and add new ones, just add them to the MixedCollection:

  
store.sorters.add(new Ext.util.Sorter({
           property : 'shoeSize',
           direction: 'ASC'
           }));
           store.sort();
            

Registering with StoreManager

Any Store that is instantiated with a storeId will automatically be registed with the StoreManager. This makes it easy to reuse the same store in multiple views:

  
//this store can be used several times
           Ext.create('Ext.data.Store', {
           model: 'User',
           storeId: 'usersStore'
           });
           new Ext.List({
           store: 'usersStore',
           //other config goes here
           });
           new Ext.view.View({
           store: 'usersStore',
           //other config goes here
           });
            

Further Reading

Stores are backed up by an ecosystem of classes that enables their operation. To gain a full understanding of these pieces and how they fit together, see:

  • Proxy - overview of what Proxies are and how they are used
  • Model - the core class in the data package
  • Reader - used by any subclass of ServerProxy to read a response

Namespace: Ext.data

Constructors

Name Description
Store(object) Creates the store.
Store(StoreConfig)
Store(Object[])

Methods

Name Description
add(Object[]) Adds Model instance to the Store. This method accepts either:
  • An array of Model instances or Model configuration objects.
  • Any number of Model instance or Model configuration object arguments.
  • The new Model instances will be added at the end of the existing collection. Sample usage:
    myStore.add({some: 'data'}, {some: 'other data'});
                
    Note that if this Store is sorted, the new Model instances will be inserted at the correct point in the Store to maintain the sort order.
    addSorted(object) (Local sort only) Inserts the passed Record into the Store at the index where it should go based on the current sort information.
    aggregate(Delegate, object, object, object) Runs the aggregate function for all the records in the store. When store is filtered, only items within the filter are aggregated.
    average(JsString, object) Gets the average value in the store. When store is filtered, only items within the filter are aggregated.
    clearFilter(object) Reverts to a view of the Record cache with no filtering applied.
    clearGrouping() Clear any groupers in the store
    collect(JsString, object, object) Collects unique values for a particular dataIndex from this store.
    commitChanges() Commits 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.
    count(object) Gets the count of items in the store. When store is filtered, only items within the filter are counted.
    each(Delegate, object) Calls the specified function for each record in the store. When store is filtered, only loops over the filtered records.
    filter(object, object) Filters the loaded set of records by a given set of filters. By default, the passed filter(s) are added to the collection of filters being used to filter this Store. To remove existing filters before applying a new set of filters use
    // Clear the filter collection without updating the UI
                store.clearFilter(true);
                
    see clearFilter. Alternatively, if filters are configured with an id, then existing filters store may be replaced by new filters having the same id. Filtering by single field:
    store.filter("email", /\.com$/);
                
    Using multiple filters:
    store.filter([
                {property: "email", value: /\.com$/},
                {filterFn: function(item) { return item.get("age") > 10; }}
                ]);
                
    Using Ext.util.Filter instances instead of config objects (note that we need to specify the root config option in this case):
    store.filter([
                Ext.create('Ext.util.Filter', {property: "email", value: /\.com$/, root: 'data'}),
                Ext.create('Ext.util.Filter', {filterFn: function(item) { return item.get("age") > 10; }, root: 'data'})
                ]);
                
    When store is filtered, most of the methods for accessing store data will be working only within the set of filtered records. Two notable exceptions are queryBy and getById.
    filterBy(Delegate, object) Filters by a function. The specified function will be called for each Record in this Store. If the function returns true the Record is included, otherwise it is filtered out. When store is filtered, most of the methods for accessing store data will be working only within the set of filtered records. Two notable exceptions are queryBy and getById.
    find(JsString, object, object, object, object, object) Finds the index of the first matching Record in this store by a specific field value. When store is filtered, finds records only within filter.
    findBy(Delegate, object, object) Find the index of the first matching Record in this Store by a function. If the function returns true it is considered a match. When store is filtered, finds records only within filter.
    findExact(JsString, object, object) Finds the index of the first matching Record in this store by a specific field value. When store is filtered, finds records only within filter.
    findRecord(JsString, object, object, object, object, object) Finds the first matching Record in this store by a specific field value. When store is filtered, finds records only within filter.
    first(object) Convenience function for getting the first model instance in the store. When store is filtered, will return first item within the filter.
    getAt(JsNumber) Get the Record at the specified index. The index is effected by filtering.
    getById(object) Get the Record with the specified id. This method is not effected by filtering, lookup will be performed from all records inside the store, filtered or not.
    getCount() Gets the number of records in store. 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 dataset size. Note: see the Important note in load. When store is filtered, it's the number of records matching the filter.
    getGroups(object) Returns an array containing the result of applying grouping to the records in this store. See groupField, groupDir and getGroupString. Example for a store containing records with a color field:
    var myStore = Ext.create('Ext.data.Store', {
                groupField: 'color',
                groupDir  : 'DESC'
                });
                myStore.getGroups(); // returns:
                [
                {
                name: 'yellow',
                children: [
                // all records where the color field is 'yellow'
                ]
                },
                {
                name: 'red',
                children: [
                // all records where the color field is 'red'
                ]
                }
                ]
                
    Group contents are effected by filtering.
    getGroupString(Model) Returns the string to group on for a given model instance. The default implementation of this method returns the model's groupField, but this can be overridden to group by an arbitrary string. For example, to group by the first letter of a model's 'name' field, use the following code:
      Ext.create('Ext.data.Store', {
                groupDir: 'ASC',
                getGroupString: function(instance) {
                return instance.get('name')[0];
                }
                });
                
    getPageFromRecordIndex(JsNumber) Determines the page from a record index
    getRange(object, object) Returns a range of Records between specified indices. This method is effected by filtering.
    getTotalCount() Returns the total number of Model instances that the Proxy indicates exist. This will usually differ from getCount when using paging - getCount returns the number of records loaded into the Store at the moment, getTotalCount returns the number of records that could be loaded into the Store if the Store contained all data
    group(object, object) Groups data inside the store.
    guaranteeRange(object, object, object, object) Guarantee a specific range, this will load the store with a range (that must be the pageSize or smaller) and take care of any loading that may be necessary.
    indexOf(Model) Get the index of the record within the store. When store is filtered, records outside of filter will not be found.
    indexOfId(JsString) Get the index within the store of the Record with the passed id. Like indexOf, this method is effected by filtering.
    indexOfTotal(Model) Get the index within the entire dataset. From 0 to the totalCount. Like indexOf, this method is effected by filtering.
    insert(JsNumber, JsArray<T>) Inserts Model instances into the Store at the given index and fires the add event. See also add.
    isFiltered() Returns true if this store is currently filtered
    isGrouped() Checks if the store is currently grouped
    last(object) Convenience function for getting the last model instance in the store. When store is filtered, will return last item within the filter.
    loadData(object, object) Loads an array of data straight into the Store. Using this method is great if the data is in the correct format already (e.g. it doesn't need to be processed by a reader). If your data requires processing to decode the data structure, use a MemoryProxy instead.
    loadPage(JsNumber, object) Loads a given 'page' of data by setting the start and limit values appropriately. Internally this just causes a normal load operation, passing in calculated 'start' and 'limit' params
    loadRawData(JsArray<T>, object) Loads data via the bound Proxy's reader Use this method if you are attempting to load data and want to utilize the configured data reader.
    loadRecords(JsArray<T>, object) Loads an array of model instances into the store, fires the datachanged event. This should only usually be called internally when loading from the Proxy, when adding records manually use add instead
    max(JsString, object) Gets the maximum value in the store. When store is filtered, only items within the filter are aggregated.
    min(JsString, object) Gets the minimum value in the store. When store is filtered, only items within the filter are aggregated.
    nextPage(object) Loads the next 'page' in the current data set
    prefetch(object) Prefetches data into the store using its configured proxy.
    prefetchPage(JsNumber, object) Prefetches a page of data.
    prefetchRange(object, object) Ensures that the specified range of rows is present in the cache. Converts the row range to a page range and then only load pages which are not already present in the page cache.
    previousPage(object) Loads the previous 'page' in the current data set
    query(JsString, object, object, object, object) Query all the cached records in this Store by name/value pair. The parameters will be used to generated a filter function that is given to the queryBy method. This method compliments queryBy by generating the query function automatically.
    queryBy(Delegate, object) Query all the cached records in this Store using a filtering function. The specified function will be called with each record in this Store. If the function returns true the record is included in the results. This method is not effected by filtering, it will always look from all records inside the store no matter if filter is applied or not.
    rejectChanges() Rejects outstanding changes on all modified records and re-insert any records that were removed locally. Any phantom records will be removed.
    remove(object) Removes the given record from the Store, firing the 'remove' event for each instance that is removed, plus a single 'datachanged' event after removal.
    removeAll(bool) Removes all items from the store.
    removeAt(JsNumber) Removes the model instance at the given index
    sum(JsString, object) Sums the value of property for each record between start and end and returns the result. When store is filtered, only sums items within the filter.

    Fields

    Name Description
    buffered Allows the Store to prefetch and cache in a page cache, pages of Records, and to then satisfy loading requirements from this page cache. To use buffered Stores, initiate the process by loading the first page. The number of rows rendered are determined automatically, and the range of pages needed to keep the cache primed for scrolling is requested and cached. Example: // Load page 1 myStore.loadPage(1); A PagingScroller is instantiated which will monitor the scrolling in the grid, and refresh the view's rows from the page cache as needed. It will also pull new data into the page cache when scrolling of the view draws upon data near either end of the prefetched data. The margins which trigger view refreshing from the prefetched data are Ext.grid.PagingScroller.numFromEdge, Ext.grid.PagingScroller.leadingBufferZone and Ext.grid.PagingScroller.trailingBufferZone. The margins which trigger loading more data into the page cache are, leadingBufferZone and trailingBufferZone. By defult, only 5 pages of data are cached in the page cache, with pages "scrolling" out of the buffer as the view moves down through the dataset. Setting this value to zero means that no pages are ever scrolled out of the page cache, and that eventually the whole dataset may become present in the page cache. This is sometimes desirable as long as datasets do not reach astronomical proportions. Selection state may be maintained across page boundaries by configuring the SelectionModel not to discard records from its collection when those Records cycle out of the Store's primary collection. This is done by configuring the SelectionModel like this: selModel: {
    pruneRemoved: false
                
    } Defaults to: false
    clearOnPageLoad True to empty the store when loading another page via loadPage, nextPage or previousPage. Setting to false keeps existing records, allowing large data sets to be loaded one page at a time but rendered all together. Defaults to: true
    clearRemovedOnLoad True to clear anything in the removed record collection when the store loads. Defaults to: true
    groupDir The direction in which sorting should be applied when grouping. Supported values are "ASC" and "DESC". Defaults to: "ASC"
    groupField The field by which to group data in the store. Internally, grouping is very similar to sorting - the groupField and groupDir are injected as the first sorter (see sort). Stores support a single level of grouping, and groups can be fetched via the getGroups method.
    leadingBufferZone When buffered, the number of extra rows to keep cached on the leading side of scrolling buffer as scrolling proceeds. A larger number means fewer replenishments from the server. Defaults to: 200
    pageSize The number of records considered to form a 'page'. This is used to power the built-in paging using the nextPage and previousPage functions when the grid is paged using a PagingScroller Defaults to 25. If this Store is buffered, pages are loaded into a page cache before the Store's data is updated from the cache. The pageSize is the number of rows loaded into the cache in one request. This will not affect the rendering of a buffered grid, but a larger page size will mean fewer loads. In a buffered grid, scrolling is monitored, and the page cache is kept primed with data ahead of the direction of scroll to provide rapid access to data when scrolling causes it to be required. Several pages in advance may be requested depending on various parameters. It is recommended to tune the pageSize, trailingBufferZone and leadingBufferZone configurations based upon the conditions pertaining in your deployed application. The provided SDK example examples/grid/infinite-scroll-grid-tuner.html can be used to experiment with different settings including simulating Ajax latency.
    purgePageCount Valid only when used with a buffered Store. The number of pages additional to the required buffered range to keep in the prefetch cache before purging least recently used records. For example, if the height of the view area and the configured trailingBufferZone and leadingBufferZone require that there are three pages in the cache, then a purgePageCount of 5 ensures that up to 8 pages can be in the page cache any any one time. A value of 0 indicates to never purge the prefetched data. Defaults to: 5
    remoteGroup True if the grouping should apply on the server side, false if it is local only. If the grouping is local, it can be applied immediately to the data. If it is remote, then it will simply act as a helper, automatically sending the grouping information to the server. Defaults to: false
    sortOnFilter For local filtering only, causes sort to be called whenever filter is called, causing the sorters to be reapplied after filtering. Defaults to true Defaults to: true
    trailingBufferZone When buffered, the number of extra records to keep cached on the trailing side of scrolling buffer as scrolling proceeds. A larger number means fewer replenishments from the server. Defaults to: 25

    Properties

    Name Description
    currentPage The page that the Store has most recently loaded (see loadPage) Defaults to: 1
    data The MixedCollection that holds this store's local cache of records.
    groupers The collection of Groupers currently applied to this Store.
    snapshot A pristine (unfiltered) collection of the records in this store. This is used to reinstate records when a filter is removed or changed
    © Copyright 2005-2011 SharpKit. All rights reserved.