4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <title>The source code</title>
6 <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7 <script type="text/javascript" src="../prettify/prettify.js"></script>
8 <style type="text/css">
9 .highlight { display: block; background-color: #ddd; }
11 <script type="text/javascript">
12 function highlight() {
13 document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
17 <body onload="prettyPrint(); highlight();">
18 <pre class="prettyprint lang-js"><span id='Ext-data-AbstractStore'>/**
19 </span> * @author Ed Spencer
20 * @class Ext.data.AbstractStore
22 * <p>AbstractStore is a superclass of {@link Ext.data.Store} and {@link Ext.data.TreeStore}. It's never used directly,
23 * but offers a set of methods used by both of those subclasses.</p>
25 * <p>We've left it here in the docs for reference purposes, but unless you need to make a whole new type of Store, what
26 * you're probably looking for is {@link Ext.data.Store}. If you're still interested, here's a brief description of what
27 * AbstractStore is and is not.</p>
29 * <p>AbstractStore provides the basic configuration for anything that can be considered a Store. It expects to be
30 * given a {@link Ext.data.Model Model} that represents the type of data in the Store. It also expects to be given a
31 * {@link Ext.data.proxy.Proxy Proxy} that handles the loading of data into the Store.</p>
33 * <p>AbstractStore provides a few helpful methods such as {@link #load} and {@link #sync}, which load and save data
34 * respectively, passing the requests through the configured {@link #proxy}. Both built-in Store subclasses add extra
35 * behavior to each of these functions. Note also that each AbstractStore subclass has its own way of storing data -
36 * in {@link Ext.data.Store} the data is saved as a flat {@link Ext.util.MixedCollection MixedCollection}, whereas in
37 * {@link Ext.data.TreeStore TreeStore} we use a {@link Ext.data.Tree} to maintain the data's hierarchy.</p>
39 * TODO: Update these docs to explain about the sortable and filterable mixins.
40 * <p>Finally, AbstractStore provides an API for sorting and filtering data via its {@link #sorters} and {@link #filters}
41 * {@link Ext.util.MixedCollection MixedCollections}. Although this functionality is provided by AbstractStore, there's a
42 * good description of how to use it in the introduction of {@link Ext.data.Store}.
45 Ext.define('Ext.data.AbstractStore', {
46 requires: ['Ext.util.MixedCollection', 'Ext.data.Operation', 'Ext.util.Filter'],
49 observable: 'Ext.util.Observable',
50 sortable: 'Ext.util.Sortable'
54 create: function(store){
59 store = Ext.createByAlias('store.' + store.type, store);
68 <span id='Ext-data-AbstractStore-cfg-proxy'> /**
69 </span> * @cfg {String/Ext.data.proxy.Proxy/Object} proxy The Proxy to use for this Store. This can be either a string, a config
70 * object or a Proxy instance - see {@link #setProxy} for details.
73 <span id='Ext-data-AbstractStore-cfg-autoLoad'> /**
74 </span> * @cfg {Boolean/Object} autoLoad If data is not specified, and if autoLoad is true or an Object, this store's load method
75 * is automatically called after creation. If the value of autoLoad is an Object, this Object will be passed to the store's
76 * load method. Defaults to false.
80 <span id='Ext-data-AbstractStore-cfg-autoSync'> /**
81 </span> * @cfg {Boolean} autoSync True to automatically sync the Store with its Proxy after every edit to one of its Records.
86 <span id='Ext-data-AbstractStore-property-batchUpdateMode'> /**
87 </span> * Sets the updating behavior based on batch synchronization. 'operation' (the default) will update the Store's
88 * internal representation of the data after each operation of the batch has completed, 'complete' will wait until
89 * the entire batch has been completed before updating the Store's data. 'complete' is a good choice for local
90 * storage proxies, 'operation' is better for remote proxies, where there is a comparatively high latency.
91 * @property batchUpdateMode
94 batchUpdateMode: 'operation',
96 <span id='Ext-data-AbstractStore-property-filterOnLoad'> /**
97 </span> * If true, any filters attached to this Store will be run after loading data, before the datachanged event is fired.
98 * Defaults to true, ignored if {@link #remoteFilter} is true
99 * @property filterOnLoad
104 <span id='Ext-data-AbstractStore-property-sortOnLoad'> /**
105 </span> * If true, any sorters attached to this Store will be run after loading data, before the datachanged event is fired.
106 * Defaults to true, igored if {@link #remoteSort} is true
107 * @property sortOnLoad
112 <span id='Ext-data-AbstractStore-property-implicitModel'> /**
113 </span> * True if a model was created implicitly for this Store. This happens if a fields array is passed to the Store's constructor
114 * instead of a model constructor or name.
115 * @property implicitModel
119 implicitModel: false,
121 <span id='Ext-data-AbstractStore-property-defaultProxyType'> /**
122 </span> * The string type of the Proxy to create if none is specified. This defaults to creating a {@link Ext.data.proxy.Memory memory proxy}.
123 * @property defaultProxyType
126 defaultProxyType: 'memory',
128 <span id='Ext-data-AbstractStore-property-isDestroyed'> /**
129 </span> * True if the Store has already been destroyed via {@link #destroyStore}. If this is true, the reference to Store should be deleted
130 * as it will not function correctly any more.
131 * @property isDestroyed
138 <span id='Ext-data-AbstractStore-cfg-storeId'> /**
139 </span> * @cfg {String} storeId Optional unique identifier for this store. If present, this Store will be registered with
140 * the {@link Ext.data.StoreManager}, making it easy to reuse elsewhere. Defaults to undefined.
143 <span id='Ext-data-AbstractStore-cfg-fields'> /**
144 </span> * @cfg {Array} fields
145 * This may be used in place of specifying a {@link #model} configuration. The fields should be a
146 * set of {@link Ext.data.Field} configuration objects. The store will automatically create a {@link Ext.data.Model}
147 * with these fields. In general this configuration option should be avoided, it exists for the purposes of
148 * backwards compatibility. For anything more complicated, such as specifying a particular id property or
149 * assocations, a {@link Ext.data.Model} should be defined and specified for the {@link #model} config.
155 constructor: function(config) {
160 <span id='Ext-data-AbstractStore-event-add'> /**
162 * Fired when a Model instance has been added to this Store
163 * @param {Ext.data.Store} store The store
164 * @param {Array} records The Model instances that were added
165 * @param {Number} index The index at which the instances were inserted
169 <span id='Ext-data-AbstractStore-event-remove'> /**
170 </span> * @event remove
171 * Fired when a Model instance has been removed from this Store
172 * @param {Ext.data.Store} store The Store object
173 * @param {Ext.data.Model} record The record that was removed
174 * @param {Number} index The index of the record that was removed
178 <span id='Ext-data-AbstractStore-event-update'> /**
179 </span> * @event update
180 * Fires when a Record has been updated
181 * @param {Store} this
182 * @param {Ext.data.Model} record The Model instance that was updated
183 * @param {String} operation The update operation being performed. Value may be one of:
184 * <pre><code>
186 Ext.data.Model.REJECT
187 Ext.data.Model.COMMIT
188 * </code></pre>
192 <span id='Ext-data-AbstractStore-event-datachanged'> /**
193 </span> * @event datachanged
194 * Fires whenever the records in the Store have changed in some way - this could include adding or removing records,
195 * or updating the data in existing records
196 * @param {Ext.data.Store} this The data store
200 <span id='Ext-data-AbstractStore-event-beforeload'> /**
201 </span> * @event beforeload
203 * @param {Ext.data.Store} store This Store
204 * @param {Ext.data.Operation} operation The Ext.data.Operation object that will be passed to the Proxy to load the Store
208 <span id='Ext-data-AbstractStore-event-load'> /**
209 </span> * @event load
210 * Fires whenever the store reads data from a remote data source.
211 * @param {Ext.data.Store} this
212 * @param {Array} records An array of records
213 * @param {Boolean} successful True if the operation was successful.
217 <span id='Ext-data-AbstractStore-event-beforesync'> /**
218 </span> * @event beforesync
219 * Called before a call to {@link #sync} is executed. Return false from any listener to cancel the synv
220 * @param {Object} options Hash of all records to be synchronized, broken down into create, update and destroy
223 <span id='Ext-data-AbstractStore-event-clear'> /**
224 </span> * @event clear
225 * Fired after the {@link #removeAll} method is called.
226 * @param {Ext.data.Store} this
231 Ext.apply(me, config);
232 // don't use *config* anymore from here on... use *me* instead...
234 <span id='Ext-data-AbstractStore-property-removed'> /**
235 </span> * Temporary cache in which removed model instances are kept until successfully synchronised with a Proxy,
236 * at which point this is cleared.
243 me.mixins.observable.constructor.apply(me, arguments);
244 me.model = Ext.ModelManager.getModel(me.model);
246 <span id='Ext-data-AbstractStore-property-modelDefaults'> /**
247 </span> * @property modelDefaults
250 * A set of default values to be applied to every model instance added via {@link #insert} or created via {@link #create}.
251 * This is used internally by associations to set foreign keys and other fields. See the Association classes source code
252 * for examples. This should not need to be used by application developers.
258 //Supports the 3.x style of simply passing an array of fields to the store, implicitly creating a model
259 if (!me.model && me.fields) {
260 me.model = Ext.define('Ext.data.Store.ImplicitModel-' + (me.storeId || Ext.id()), {
261 extend: 'Ext.data.Model',
263 proxy: me.proxy || me.defaultProxyType
268 me.implicitModel = true;
271 //ensures that the Proxy is instantiated correctly
272 me.setProxy(me.proxy || me.model.getProxy());
274 if (me.id && !me.storeId) {
280 Ext.data.StoreManager.register(me);
283 me.mixins.sortable.initSortable.call(me);
285 <span id='Ext-data-AbstractStore-property-filters'> /**
286 </span> * The collection of {@link Ext.util.Filter Filters} currently applied to this Store
288 * @type Ext.util.MixedCollection
290 filters = me.decodeFilters(me.filters);
291 me.filters = Ext.create('Ext.util.MixedCollection');
292 me.filters.addAll(filters);
295 <span id='Ext-data-AbstractStore-method-setProxy'> /**
296 </span> * Sets the Store's Proxy by string, config object or Proxy instance
297 * @param {String|Object|Ext.data.proxy.Proxy} proxy The new Proxy, which can be either a type string, a configuration object
298 * or an Ext.data.proxy.Proxy instance
299 * @return {Ext.data.proxy.Proxy} The attached Proxy object
301 setProxy: function(proxy) {
304 if (proxy instanceof Ext.data.proxy.Proxy) {
305 proxy.setModel(me.model);
307 if (Ext.isString(proxy)) {
316 proxy = Ext.createByAlias('proxy.' + proxy.type, proxy);
324 <span id='Ext-data-AbstractStore-method-getProxy'> /**
325 </span> * Returns the proxy currently attached to this proxy instance
326 * @return {Ext.data.proxy.Proxy} The Proxy instance
328 getProxy: function() {
332 //saves any phantom records
333 create: function(data, options) {
335 instance = Ext.ModelManager.create(Ext.applyIf(data, me.modelDefaults), me.model.modelName),
338 options = options || {};
340 Ext.applyIf(options, {
345 operation = Ext.create('Ext.data.Operation', options);
347 me.proxy.create(operation, me.onProxyWrite, me);
353 return this.load.apply(this, arguments);
356 onProxyRead: Ext.emptyFn,
358 update: function(options) {
361 options = options || {};
363 Ext.applyIf(options, {
365 records: me.getUpdatedRecords()
368 operation = Ext.create('Ext.data.Operation', options);
370 return me.proxy.update(operation, me.onProxyWrite, me);
373 <span id='Ext-data-AbstractStore-method-onProxyWrite'> /**
375 * Callback for any write Operation over the Proxy. Updates the Store's MixedCollection to reflect
376 * the updates provided by the Proxy
378 onProxyWrite: function(operation) {
380 success = operation.wasSuccessful(),
381 records = operation.getRecords();
383 switch (operation.action) {
385 me.onCreateRecords(records, operation, success);
388 me.onUpdateRecords(records, operation, success);
391 me.onDestroyRecords(records, operation, success);
396 me.fireEvent('write', me, operation);
397 me.fireEvent('datachanged', me);
399 //this is a callback that would have been passed to the 'create', 'update' or 'destroy' function and is optional
400 Ext.callback(operation.callback, operation.scope || me, [records, operation, success]);
404 //tells the attached proxy to destroy the given records
405 destroy: function(options) {
409 options = options || {};
411 Ext.applyIf(options, {
413 records: me.getRemovedRecords()
416 operation = Ext.create('Ext.data.Operation', options);
418 return me.proxy.destroy(operation, me.onProxyWrite, me);
421 <span id='Ext-data-AbstractStore-method-onBatchOperationComplete'> /**
423 * Attached as the 'operationcomplete' event listener to a proxy's Batch object. By default just calls through
426 onBatchOperationComplete: function(batch, operation) {
427 return this.onProxyWrite(operation);
430 <span id='Ext-data-AbstractStore-method-onBatchComplete'> /**
432 * Attached as the 'complete' event listener to a proxy's Batch object. Iterates over the batch operations
433 * and updates the Store's internal data MixedCollection.
435 onBatchComplete: function(batch, operation) {
437 operations = batch.operations,
438 length = operations.length,
443 for (i = 0; i < length; i++) {
444 me.onProxyWrite(operations[i]);
449 me.fireEvent('datachanged', me);
452 onBatchException: function(batch, operation) {
453 // //decide what to do... could continue with the next operation
456 // //or retry the last operation
460 <span id='Ext-data-AbstractStore-method-filterNew'> /**
462 * Filter function for new records.
464 filterNew: function(item) {
465 // only want phantom records that are valid
466 return item.phantom === true && item.isValid();
469 <span id='Ext-data-AbstractStore-method-getNewRecords'> /**
470 </span> * Returns all Model instances that are either currently a phantom (e.g. have no id), or have an ID but have not
471 * yet been saved on this Store (this happens when adding a non-phantom record from another Store into this one)
472 * @return {Array} The Model instances
474 getNewRecords: function() {
478 <span id='Ext-data-AbstractStore-method-getUpdatedRecords'> /**
479 </span> * Returns all Model instances that have been updated in the Store but not yet synchronized with the Proxy
480 * @return {Array} The updated Model instances
482 getUpdatedRecords: function() {
486 <span id='Ext-data-AbstractStore-method-filterUpdated'> /**
488 * Filter function for updated records.
490 filterUpdated: function(item) {
491 // only want dirty records, not phantoms that are valid
492 return item.dirty === true && item.phantom !== true && item.isValid();
495 <span id='Ext-data-AbstractStore-method-getRemovedRecords'> /**
496 </span> * Returns any records that have been removed from the store but not yet destroyed on the proxy.
497 * @return {Array} The removed Model instances
499 getRemovedRecords: function() {
503 filter: function(filters, value) {
507 <span id='Ext-data-AbstractStore-method-decodeFilters'> /**
509 * Normalizes an array of filter objects, ensuring that they are all Ext.util.Filter instances
510 * @param {Array} filters The filters array
511 * @return {Array} Array of Ext.util.Filter objects
513 decodeFilters: function(filters) {
514 if (!Ext.isArray(filters)) {
515 if (filters === undefined) {
522 var length = filters.length,
523 Filter = Ext.util.Filter,
526 for (i = 0; i < length; i++) {
529 if (!(config instanceof Filter)) {
534 //support for 3.x style filters where a function can be defined as 'fn'
536 config.filterFn = config.fn;
539 //support a function to be passed as a filter definition
540 if (typeof config == 'function') {
546 filters[i] = new Filter(config);
553 clearFilter: function(supressEvent) {
557 isFiltered: function() {
561 filterBy: function(fn, scope) {
565 <span id='Ext-data-AbstractStore-method-sync'> /**
566 </span> * Synchronizes the Store with its Proxy. This asks the Proxy to batch together any new, updated
567 * and deleted records in the store, updating the Store's internal representation of the records
568 * as each operation completes.
573 toCreate = me.getNewRecords(),
574 toUpdate = me.getUpdatedRecords(),
575 toDestroy = me.getRemovedRecords(),
578 if (toCreate.length > 0) {
579 options.create = toCreate;
583 if (toUpdate.length > 0) {
584 options.update = toUpdate;
588 if (toDestroy.length > 0) {
589 options.destroy = toDestroy;
593 if (needsSync && me.fireEvent('beforesync', options) !== false) {
594 me.proxy.batch(options, me.getBatchListeners());
599 <span id='Ext-data-AbstractStore-method-getBatchListeners'> /**
601 * Returns an object which is passed in as the listeners argument to proxy.batch inside this.sync.
602 * This is broken out into a separate function to allow for customisation of the listeners
603 * @return {Object} The listeners object
605 getBatchListeners: function() {
609 exception: me.onBatchException
612 if (me.batchUpdateMode == 'operation') {
613 listeners.operationcomplete = me.onBatchOperationComplete;
615 listeners.complete = me.onBatchComplete;
621 //deprecated, will be removed in 5.0
623 return this.sync.apply(this, arguments);
626 <span id='Ext-data-AbstractStore-method-load'> /**
627 </span> * Loads the Store using its configured {@link #proxy}.
628 * @param {Object} options Optional config object. This is passed into the {@link Ext.data.Operation Operation}
629 * object that is created and then sent to the proxy's {@link Ext.data.proxy.Proxy#read} function
631 load: function(options) {
635 options = options || {};
637 Ext.applyIf(options, {
639 filters: me.filters.items,
640 sorters: me.getSorters()
643 operation = Ext.create('Ext.data.Operation', options);
645 if (me.fireEvent('beforeload', me, operation) !== false) {
647 me.proxy.read(operation, me.onProxyLoad, me);
653 <span id='Ext-data-AbstractStore-method-afterEdit'> /**
655 * A model instance should call this method on the Store it has been {@link Ext.data.Model#join joined} to.
656 * @param {Ext.data.Model} record The model instance that was edited
658 afterEdit : function(record) {
665 me.fireEvent('update', me, record, Ext.data.Model.EDIT);
668 <span id='Ext-data-AbstractStore-method-afterReject'> /**
670 * A model instance should call this method on the Store it has been {@link Ext.data.Model#join joined} to..
671 * @param {Ext.data.Model} record The model instance that was edited
673 afterReject : function(record) {
674 this.fireEvent('update', this, record, Ext.data.Model.REJECT);
677 <span id='Ext-data-AbstractStore-method-afterCommit'> /**
679 * A model instance should call this method on the Store it has been {@link Ext.data.Model#join joined} to.
680 * @param {Ext.data.Model} record The model instance that was edited
682 afterCommit : function(record) {
683 this.fireEvent('update', this, record, Ext.data.Model.COMMIT);
686 clearData: Ext.emptyFn,
688 destroyStore: function() {
691 if (!me.isDestroyed) {
693 Ext.data.StoreManager.unregister(me);
698 // Ext.destroy(this.proxy);
699 me.reader = me.writer = null;
701 me.isDestroyed = true;
703 if (me.implicitModel) {
704 Ext.destroy(me.model);
709 doSort: function(sorterFn) {
712 //the load function will pick up the new sorters and request the sorted data from the proxy
715 me.data.sortBy(sorterFn);
716 me.fireEvent('datachanged', me);
720 getCount: Ext.emptyFn,
722 getById: Ext.emptyFn,
724 <span id='Ext-data-AbstractStore-method-removeAll'> /**
725 </span> * Removes all records from the store. This method does a "fast remove",
726 * individual remove events are not called. The {@link #clear} event is
727 * fired upon completion.
730 removeAll: Ext.emptyFn,
731 // individual substores should implement a "fast" remove
732 // and fire a clear event afterwards
734 <span id='Ext-data-AbstractStore-method-isLoading'> /**
735 </span> * Returns true if the Store is currently performing a load operation
736 * @return {Boolean} True if the Store is currently loading
738 isLoading: function() {