X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..6746dc89c47ed01b165cc1152533605f97eb8e8d:/docs/source/Store2.html diff --git a/docs/source/Store2.html b/docs/source/Store2.html index d928b579..df20a51c 100644 --- a/docs/source/Store2.html +++ b/docs/source/Store2.html @@ -1,5 +1,22 @@ -
+ +/** - * @author Ed Spencer + + + + +\ No newline at end of file +The source code + + + + + + +/** + * @author Ed Spencer * @class Ext.data.Store * @extends Ext.data.AbstractStore * @@ -207,8 +224,6 @@ new Ext.view.View({ * <li>{@link Ext.data.reader.Reader Reader} - used by any subclass of {@link Ext.data.proxy.Server ServerProxy} to read a response</li> * </ul> * - * @constructor - * @param {Object} config Optional config object */ Ext.define('Ext.data.Store', { extend: 'Ext.data.AbstractStore', @@ -218,19 +233,19 @@ Ext.define('Ext.data.Store', { requires: ['Ext.ModelManager', 'Ext.data.Model', 'Ext.util.Grouper'], uses: ['Ext.data.proxy.Memory'], - /** + /** * @cfg {Boolean} remoteSort * True to defer any sorting operation to the server. If false, sorting is done locally on the client. Defaults to <tt>false</tt>. */ remoteSort: false, - /** + /** * @cfg {Boolean} remoteFilter * True to defer any filtering operation to the server. If false, filtering is done locally on the client. Defaults to <tt>false</tt>. */ remoteFilter: false, - /** + /** * @cfg {Boolean} remoteGroup * True if the grouping should apply on the server side, false if it is local only (defaults to false). If the * grouping is local, it can be applied immediately to the data. If it is remote, then it will simply act as a @@ -238,20 +253,20 @@ Ext.define('Ext.data.Store', { */ remoteGroup : false, - /** + /** * @cfg {String/Ext.data.proxy.Proxy/Object} proxy The Proxy to use for this Store. This can be either a string, a config * object or a Proxy instance - see {@link #setProxy} for details. */ - /** + /** * @cfg {Array} data Optional array of Model instances or data objects to load locally. See "Inline data" above for details. */ - /** + /** * @cfg {String} model The {@link Ext.data.Model} associated with this store */ - /** + /** * The (optional) field by which to group data in the store. Internally, grouping is very similar to sorting - the * groupField and {@link #groupDir} are injected as the first sorter (see {@link #sort}). Stores support a single * level of grouping, and groups can be fetched via the {@link #getGroups} method. @@ -260,36 +275,35 @@ Ext.define('Ext.data.Store', { */ groupField: undefined, - /** + /** * The direction in which sorting should be applied when grouping. Defaults to "ASC" - the other supported value is "DESC" * @property groupDir * @type String */ groupDir: "ASC", - /** - * The number of records considered to form a 'page'. This is used to power the built-in + /** + * @cfg {Number} 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. Defaults to 25. - * @property pageSize - * @type Number */ pageSize: 25, - /** + /** * The page that the Store has most recently loaded (see {@link #loadPage}) * @property currentPage * @type Number */ currentPage: 1, - /** + /** * @cfg {Boolean} clearOnPageLoad True to empty the store when loading another page via {@link #loadPage}, * {@link #nextPage} or {@link #previousPage} (defaults to true). Setting to false keeps existing records, allowing * large data sets to be loaded one page at a time but rendered all together. */ clearOnPageLoad: true, - /** + /** * True if the Store is currently loading via its Proxy * @property loading * @type Boolean @@ -297,20 +311,20 @@ Ext.define('Ext.data.Store', { */ loading: false, - /** + /** * @cfg {Boolean} sortOnFilter For local filtering only, causes {@link #sort} to be called whenever {@link #filter} is called, * causing the sorters to be reapplied after filtering. Defaults to true */ sortOnFilter: true, - /** + /** * @cfg {Boolean} buffered * Allow the store to buffer and pre-fetch pages of records. This is to be used in conjunction with a view will * tell the store to pre-fetch records ahead of a time. */ buffered: false, - /** + /** * @cfg {Number} purgePageCount * The number of pages to keep in the cache before purging additional records. A value of 0 indicates to never purge the prefetched data. * This option is only relevant when the {@link #buffered} option is set to true. @@ -319,12 +333,16 @@ Ext.define('Ext.data.Store', { isStore: true, - //documented above + /** + * Creates the store. + * @param {Object} config (optional) Config object + */ constructor: function(config) { config = config || {}; var me = this, - groupers = config.groupers, + groupers = config.groupers || me.groupers, + groupField = config.groupField || me.groupField, proxy, data; @@ -340,21 +358,21 @@ Ext.define('Ext.data.Store', { } me.addEvents( - /** + /** * @event beforeprefetch * Fires before a prefetch occurs. Return false to cancel. * @param {Ext.data.store} this * @param {Ext.data.Operation} operation The associated operation */ 'beforeprefetch', - /** + /** * @event groupchange * Fired whenever the grouping in the grid changes * @param {Ext.data.Store} store The store * @param {Array} groupers The array of grouper objects */ 'groupchange', - /** + /** * @event load * Fires whenever records have been prefetched * @param {Ext.data.store} this @@ -366,7 +384,7 @@ Ext.define('Ext.data.Store', { ); data = config.data || me.data; - /** + /** * The MixedCollection that holds this store's local cache of records * @property data * @type Ext.util.MixedCollection @@ -380,15 +398,15 @@ Ext.define('Ext.data.Store', { delete config.data; } - if (!groupers && config.groupField) { + if (!groupers && groupField) { groupers = [{ - property : config.groupField, - direction: config.groupDir + property : groupField, + direction: config.groupDir || me.groupDir }]; } delete config.groupers; - /** + /** * The collection of {@link Ext.util.Grouper Groupers} currently applied to this Store * @property groupers * @type Ext.util.MixedCollection @@ -397,6 +415,7 @@ Ext.define('Ext.data.Store', { me.groupers.addAll(me.decodeGroupers(groupers)); this.callParent([config]); + // don't use *config* anymore from here on... use *me* instead... if (me.groupers.items.length) { me.sort(me.groupers.items, 'prepend', false); @@ -426,7 +445,7 @@ Ext.define('Ext.data.Store', { this.sort(this.groupers.items, 'prepend', false); }, - /** + /** * @private * Normalizes an array of grouper objects, ensuring that they are all Ext.util.Grouper instances * @param {Array} groupers The groupers array @@ -479,7 +498,7 @@ Ext.define('Ext.data.Store', { return groupers; }, - /** + /** * Group data in the store * @param {String|Array} groupers Either a string name of one of the fields in this Store's configured {@link Ext.data.Model Model}, * or an Array of grouper configurations. @@ -527,7 +546,7 @@ Ext.define('Ext.data.Store', { } }, - /** + /** * Clear any groupers in the store */ clearGrouping: function(){ @@ -548,7 +567,7 @@ Ext.define('Ext.data.Store', { } }, - /** + /** * Checks if the store is currently grouped * @return {Boolean} True if the store is grouped. */ @@ -556,7 +575,7 @@ Ext.define('Ext.data.Store', { return this.groupers.getCount() > 0; }, - /** + /** * Fires the groupchange event. Abstracted out so we can use it * as a callback * @private @@ -565,7 +584,7 @@ Ext.define('Ext.data.Store', { this.fireEvent('groupchange', this, this.groupers); }, - /** + /** * Returns an object containing the result of applying grouping to the records in this store. See {@link #groupField}, * {@link #groupDir} and {@link #getGroupString}. Example for a store containing records with a color field: <pre><code> @@ -624,7 +643,7 @@ myStore.getGroups(); //returns: return requestGroupString ? pointers[requestGroupString] : groups; }, - /** + /** * @private * For a given set of records and a Grouper, returns an array of arrays - each of which is the set of records * matching a certain group. @@ -659,7 +678,7 @@ myStore.getGroups(); //returns: return groups; }, - /** + /** * @private * This is used recursively to gather the records into the configured Groupers. The data MUST have been sorted for * this to work properly (see {@link #getGroupData} and {@link #getGroupsForGrouper}) Most of the work is done by @@ -689,7 +708,7 @@ myStore.getGroups(); //returns: return groups; }, - /** + /** * @private * <p>Returns records grouped by the configured {@link #groupers grouper} configuration. Sample return value (in * this case grouping by genre and then author in a fictional books dataset):</p> @@ -734,7 +753,7 @@ myStore.getGroups(); //returns: return me.getGroupsForGrouperIndex(me.data.items, 0); }, - /** + /** * <p>Returns the string to group on for a given model instance. The default implementation of this method returns * the model's {@link #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:</p> @@ -756,7 +775,7 @@ new Ext.data.Store({ } return ''; }, - /** + /** * Inserts Model instances into the Store at the given index and fires the {@link #add} event. * See also <code>{@link #add}</code>. * @param {Number} index The start index at which to insert the passed Records. @@ -793,7 +812,7 @@ new Ext.data.Store({ } }, - /** + /** * Adds Model instances to the Store by instantiating them based on a JavaScript object. When adding already- * instantiated Models, use {@link #insert} instead. The instances will be added at the end of the existing collection. * This method accepts either a single argument array of Model instances or any number of model instance arguments. @@ -828,7 +847,7 @@ myStore.add({some: 'data'}, {some: 'other data'}); return records; }, - /** + /** * Converts a literal to a model, if it's not a model already * @private * @param record {Ext.data.Model/Object} The record to create @@ -842,7 +861,7 @@ myStore.add({some: 'data'}, {some: 'other data'}); return record; }, - /** + /** * Calls the specified function for each of the {@link Ext.data.Model Records} in the cache. * @param {Function} fn The function to call. The {@link Ext.data.Model Record} is passed as the first parameter. * Returning <tt>false</tt> aborts and exits the iteration. @@ -853,7 +872,7 @@ myStore.add({some: 'data'}, {some: 'other data'}); this.data.each(fn, scope); }, - /** + /** * Removes the given record from the Store, firing the 'remove' event for each instance that is removed, plus a single * 'datachanged' event after removal. * @param {Ext.data.Model/Array} records The Ext.data.Model instance or array of instances to remove @@ -904,7 +923,7 @@ myStore.add({some: 'data'}, {some: 'other data'}); } }, - /** + /** * Removes the model instance at the given index * @param {Number} index The record index */ @@ -916,7 +935,7 @@ myStore.add({some: 'data'}, {some: 'other data'}); } }, - /** + /** * <p>Loads data into the Store via the configured {@link #proxy}. This uses the Proxy to make an * asynchronous call to whatever storage backend the Proxy uses, automatically adding the retrieved * instances into the Store and calling an optional callback if required. Example usage:</p> @@ -963,7 +982,7 @@ store.load(function(records, operation, success) { return me.callParent([options]); }, - /** + /** * @private * Called internally when a Proxy has completed a load request */ @@ -992,7 +1011,7 @@ store.load(function(records, operation, success) { Ext.callback(operation.callback, operation.scope || me, [records, operation, successful]); }, - /** + /** * Create any new records when a write is returned from the server. * @private * @param {Array} records The array of new records @@ -1010,8 +1029,8 @@ store.load(function(records, operation, success) { original, index; - /** - * Loop over each record returned from the server. Assume they are + /* + * Loop over each record returned from the server. Assume they are * returned in order of how they were sent. If we find a matching * record, replace it with the newly created one. */ @@ -1038,7 +1057,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Update any records when a write is returned from the server. * @private * @param {Array} records The array of updated records @@ -1064,7 +1083,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Remove any records when a write is returned from the server. * @private * @param {Array} records The array of removed records @@ -1102,7 +1121,7 @@ store.load(function(records, operation, success) { return this.data.filterBy(this.filterUpdated).items; }, - /** + /** * Filters the loaded set of records by a given set of filters. * @param {Mixed} filters The set of filters to apply to the data. These are stored internally on the store, * but the filtering itself is done on the Store's {@link Ext.util.MixedCollection MixedCollection}. See @@ -1132,7 +1151,7 @@ store.load(function(records, operation, success) { //the load function will pick up the new filters and request the filtered data from the proxy me.load(); } else { - /** + /** * A pristine (unfiltered) collection of the records in this store. This is used to reinstate * records when a filter is removed or changed * @property snapshot @@ -1153,7 +1172,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Revert to a view of the Record cache with no filtering applied. * @param {Boolean} suppressEvent If <tt>true</tt> the filter is cleared silently without firing the * {@link #datachanged} event. @@ -1175,7 +1194,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Returns true if this store is currently filtered * @return {Boolean} */ @@ -1184,7 +1203,7 @@ store.load(function(records, operation, success) { return !! snapshot && snapshot !== this.data; }, - /** + /** * Filter by a function. The specified function will be called for each * Record in this Store. If the function returns <tt>true</tt> the Record is included, * otherwise it is filtered out. @@ -1203,7 +1222,7 @@ store.load(function(records, operation, success) { me.fireEvent('datachanged', me); }, - /** + /** * Query 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 <tt>true</tt> the record is * included in the results. @@ -1221,7 +1240,7 @@ store.load(function(records, operation, success) { return data.filterBy(fn, scope || me); }, - /** + /** * Loads an array of data straight into the Store * @param {Array} data Array of data to load. Any non-model instances will be cast into model instances first * @param {Boolean} append True to add the records to the existing records in the store, false to remove the old ones first @@ -1244,7 +1263,7 @@ store.load(function(records, operation, success) { this.loadRecords(data, {addRecords: append}); }, - /** + /** * Loads an array of {@Ext.data.Model model} instances into the store, fires the datachanged event. This should only usually * be called internally when loading from the {@link Ext.data.proxy.Proxy Proxy}, when adding records manually use {@link #add} instead * @param {Array} records The array of records to load @@ -1260,7 +1279,7 @@ store.load(function(records, operation, success) { if (!options.addRecords) { delete me.snapshot; - me.data.clear(); + me.clearData(); } me.data.addAll(records); @@ -1294,7 +1313,7 @@ store.load(function(records, operation, success) { }, // PAGING METHODS - /** + /** * 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 * @param {Number} page The number of the page to load @@ -1312,14 +1331,14 @@ store.load(function(records, operation, success) { }); }, - /** + /** * Loads the next 'page' in the current data set */ nextPage: function() { this.loadPage(this.currentPage + 1); }, - /** + /** * Loads the previous 'page' in the current data set */ previousPage: function() { @@ -1336,7 +1355,7 @@ store.load(function(records, operation, success) { }, // Buffering - /** + /** * Prefetches data the Store using its configured {@link #proxy}. * @param {Object} options Optional config object, passed into the Ext.data.Operation object before loading. * See {@link #load} @@ -1370,7 +1389,7 @@ store.load(function(records, operation, success) { return me; }, - /** + /** * Prefetches a page of data. * @param {Number} page The page to prefetch * @param {Object} options Optional config object, passed into the Ext.data.Operation object before loading. @@ -1400,7 +1419,7 @@ store.load(function(records, operation, success) { }, - /** + /** * Returns a unique requestId to track requests. * @private */ @@ -1409,7 +1428,7 @@ store.load(function(records, operation, success) { return this.requestSeed++; }, - /** + /** * Handles a success pre-fetch * @private * @param {Ext.data.Operation} operation The operation that completed @@ -1446,7 +1465,7 @@ store.load(function(records, operation, success) { Ext.callback(operation.callback, operation.scope || me, [records, operation, successful]); }, - /** + /** * Caches the records in the prefetch and stripes them with their server-side * index. * @private @@ -1477,7 +1496,7 @@ store.load(function(records, operation, success) { }, - /** + /** * Purge the least recently used records in the prefetch if the purgeCount * has been exceeded. */ @@ -1493,7 +1512,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Determines if the range has already been satisfied in the prefetchData. * @private * @param {Number} start The start index @@ -1518,7 +1537,7 @@ store.load(function(records, operation, success) { return satisfied; }, - /** + /** * Determines the page from a record index * @param {Number} index The record index * @return {Number} The page the record belongs to @@ -1527,7 +1546,7 @@ store.load(function(records, operation, success) { return Math.floor(index / this.pageSize) + 1; }, - /** + /** * Handles a guaranteed range being loaded * @private */ @@ -1581,7 +1600,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Returns the number of pending requests out. */ hasPendingRequests: function() { @@ -1596,7 +1615,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * 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. @@ -1679,7 +1698,6 @@ store.load(function(records, operation, success) { sorters = me.getSorters(); start = me.guaranteedStart; end = me.guaranteedEnd; - range; if (sorters.length) { prefetchData.sort(sorters); @@ -1719,7 +1737,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Finds the index of the first matching Record in this store by a specific field value. * @param {String} fieldName The name of the Record field to test. * @param {String/RegExp} value Either a string that the field value @@ -1735,7 +1753,7 @@ store.load(function(records, operation, success) { return fn ? this.data.findIndexBy(fn, null, start) : -1; }, - /** + /** * Finds the first matching Record in this store by a specific field value. * @param {String} fieldName The name of the Record field to test. * @param {String/RegExp} value Either a string that the field value @@ -1752,7 +1770,7 @@ store.load(function(records, operation, success) { return index !== -1 ? me.getAt(index) : null; }, - /** + /** * @private * Returns a filter function used to test a the given property's value. Defers most of the work to * Ext.util.MixedCollection's createValueMatcher function @@ -1773,7 +1791,7 @@ store.load(function(records, operation, success) { }; }, - /** + /** * Finds the index of the first matching Record in this store by a specific field value. * @param {String} fieldName The name of the Record field to test. * @param {Mixed} value The value to match the field against. @@ -1787,7 +1805,7 @@ store.load(function(records, operation, success) { this, start); }, - /** + /** * Find the index of the first matching Record in this Store by a function. * If the function returns <tt>true</tt> it is considered a match. * @param {Function} fn The function to be called. It will be passed the following parameters:<ul> @@ -1803,7 +1821,7 @@ store.load(function(records, operation, success) { return this.data.findIndexBy(fn, scope, start); }, - /** + /** * Collects unique values for a particular dataIndex from this store. * @param {String} dataIndex The property to collect * @param {Boolean} allowNull (optional) Pass true to allow null, undefined or empty string values @@ -1817,7 +1835,7 @@ store.load(function(records, operation, success) { return data.collect(dataIndex, 'data', allowNull); }, - /** + /** * Gets the number of cached records. * <p>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 {@link #getTotalCount} function returns @@ -1828,7 +1846,7 @@ store.load(function(records, operation, success) { return this.data.length || 0; }, - /** + /** * Returns the total number of {@link Ext.data.Model Model} instances that the {@link Ext.data.proxy.Proxy Proxy} * indicates exist. This will usually differ from {@link #getCount} when using paging - getCount returns the * number of records loaded into the Store at the moment, getTotalCount returns the number of records that @@ -1839,7 +1857,7 @@ store.load(function(records, operation, success) { return this.totalCount; }, - /** + /** * Get the Record at the specified index. * @param {Number} index The index of the Record to find. * @return {Ext.data.Model} The Record at the passed index. Returns undefined if not found. @@ -1848,7 +1866,7 @@ store.load(function(records, operation, success) { return this.data.getAt(index); }, - /** + /** * Returns a range of Records between specified indices. * @param {Number} startIndex (optional) The starting index (defaults to 0) * @param {Number} endIndex (optional) The ending index (defaults to the last Record in the Store) @@ -1858,7 +1876,7 @@ store.load(function(records, operation, success) { return this.data.getRange(start, end); }, - /** + /** * Get the Record with the specified id. * @param {String} id The id of the Record to find. * @return {Ext.data.Model} The Record with the passed id. Returns undefined if not found. @@ -1869,7 +1887,7 @@ store.load(function(records, operation, success) { }); }, - /** + /** * Get the index within the cache of the passed Record. * @param {Ext.data.Model} record The Ext.data.Model object to find. * @return {Number} The index of the passed Record. Returns -1 if not found. @@ -1879,7 +1897,7 @@ store.load(function(records, operation, success) { }, - /** + /** * Get the index within the entire dataset. From 0 to the totalCount. * @param {Ext.data.Model} record The Ext.data.Model object to find. * @return {Number} The index of the passed Record. Returns -1 if not found. @@ -1888,7 +1906,7 @@ store.load(function(records, operation, success) { return record.index || this.indexOf(record); }, - /** + /** * Get the index within the cache of the Record with the passed id. * @param {String} id The id of the Record to find. * @return {Number} The index of the Record. Returns -1 if not found. @@ -1897,7 +1915,7 @@ store.load(function(records, operation, success) { return this.data.indexOfKey(id); }, - /** + /** * Remove all items from the store. * @param {Boolean} silent Prevent the `clear` event from being fired. */ @@ -1917,7 +1935,7 @@ store.load(function(records, operation, success) { * Aggregation methods */ - /** + /** * Convenience function for getting the first model instance in the store * @param {Boolean} grouped (Optional) True to perform the operation for each group * in the store. The value returned will be an object literal with the key being the group @@ -1937,7 +1955,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Convenience function for getting the last model instance in the store * @param {Boolean} grouped (Optional) True to perform the operation for each group * in the store. The value returned will be an object literal with the key being the group @@ -1958,7 +1976,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Sums the value of <tt>property</tt> for each {@link Ext.data.Model record} between <tt>start</tt> * and <tt>end</tt> and returns the result. * @param {String} field A field in each record @@ -1991,7 +2009,7 @@ store.load(function(records, operation, success) { return total; }, - /** + /** * Gets the count of items in the store. * @param {Boolean} grouped (Optional) True to perform the operation for each group * in the store. The value returned will be an object literal with the key being the group @@ -2011,7 +2029,7 @@ store.load(function(records, operation, success) { } }, - /** + /** * Gets the minimum value in the store. * @param {String} field The field in each record * @param {Boolean} grouped (Optional) True to perform the operation for each group @@ -2049,7 +2067,7 @@ store.load(function(records, operation, success) { return min; }, - /** + /** * Gets the maximum value in the store. * @param {String} field The field in each record * @param {Boolean} grouped (Optional) True to perform the operation for each group @@ -2088,7 +2106,7 @@ store.load(function(records, operation, success) { return max; }, - /** + /** * Gets the average value in the store. * @param {String} field The field in each record * @param {Boolean} grouped (Optional) True to perform the operation for each group @@ -2121,7 +2139,7 @@ store.load(function(records, operation, success) { return 0; }, - /** + /** * Runs the aggregate function for all the records in the store. * @param {Function} fn The function to execute. The function is called with a single parameter, * an array of records for that group. @@ -2152,4 +2170,6 @@ store.load(function(records, operation, success) { } } }); -