/**
+ * @author Ed Spencer
* @class Ext.data.Store
* @extends Ext.data.AbstractStore
*
@@ -21,7 +38,7 @@ Ext.define('User', {
]
});
-var myStore = new Ext.data.Store({
+var myStore = Ext.create('Ext.data.Store', {
model: 'User',
proxy: {
type: 'ajax',
@@ -45,7 +62,7 @@ var myStore = new Ext.data.Store({
* into Model instances:</p>
*
<pre><code>
-new Ext.data.Store({
+Ext.create('Ext.data.Store', {
model: 'User',
data : [
{firstName: 'Ed', lastName: 'Spencer'},
@@ -70,7 +87,7 @@ new Ext.data.Store({
* docs for a full explanation:</p>
*
<pre><code>
-var store = new Ext.data.Store({
+var store = Ext.create('Ext.data.Store', {
autoLoad: true,
model: "User",
proxy: {
@@ -118,7 +135,7 @@ var store = new Ext.data.Store({
* either just specify sorters and filters in the Store configuration or call {@link #sort} or {@link #filter}:
*
<pre><code>
-var store = new Ext.data.Store({
+var store = Ext.create('Ext.data.Store', {
model: 'User',
sorters: [
{
@@ -178,7 +195,7 @@ store.sort();
*
<pre><code>
//this store can be used several times
-new Ext.data.Store({
+Ext.create('Ext.data.Store', {
model: 'User',
storeId: 'usersStore'
});
@@ -207,111 +224,102 @@ 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',
alias: 'store.store',
- requires: ['Ext.ModelManager', 'Ext.data.Model', 'Ext.util.Grouper'],
+ requires: ['Ext.data.StoreManager', '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
+ * 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.
*/
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
+ /**
+ * @cfg {Object[]/Ext.data.Model[]} data Optional array of Model instances or data objects to load locally. See "Inline data" above for details.
*/
- /**
- * The (optional) field by which to group data in the store. Internally, grouping is very similar to sorting - the
+ /**
+ * @property {String} groupField
+ * The 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.
- * @property groupField
- * @type String
*/
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
+ * {@link #nextPage} or {@link #previousPage}. 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
+ /**
+ * @property {Boolean} loading
+ * True if the Store is currently loading via its Proxy
* @private
*/
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
+
+ /**
+ * @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,46 +327,67 @@ Ext.define('Ext.data.Store', {
isStore: true,
- //documented above
+ onClassExtended: function(cls, data) {
+ var model = data.model;
+
+ if (typeof model == 'string') {
+ var onBeforeClassCreated = data.onBeforeClassCreated;
+
+ data.onBeforeClassCreated = function(cls, data) {
+ var me = this;
+
+ Ext.require(model, function() {
+ onBeforeClassCreated.call(me, cls, data);
+ });
+ };
+ }
+ },
+
+ /**
+ * Creates the store.
+ * @param {Object} config (optional) Config object
+ */
constructor: function(config) {
- config = config || {};
+ // Clone the config so we don't modify the original config object
+ config = Ext.Object.merge({}, config);
var me = this,
- groupers = config.groupers,
+ groupers = config.groupers || me.groupers,
+ groupField = config.groupField || me.groupField,
proxy,
data;
-
+
if (config.buffered || me.buffered) {
me.prefetchData = Ext.create('Ext.util.MixedCollection', false, function(record) {
return record.index;
});
me.pendingRequests = [];
me.pagesRequested = [];
-
+
me.sortOnLoad = false;
me.filterOnLoad = false;
}
-
+
me.addEvents(
- /**
+ /**
* @event beforeprefetch
* Fires before a prefetch occurs. Return false to cancel.
- * @param {Ext.data.store} this
+ * @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
+ * @param {Ext.util.Grouper[]} groupers The array of grouper objects
*/
'groupchange',
- /**
+ /**
* @event load
* Fires whenever records have been prefetched
- * @param {Ext.data.store} this
- * @param {Array} records An array of records
+ * @param {Ext.data.Store} this
+ * @param {Ext.util.Grouper[]} records An array of records
* @param {Boolean} successful True if the operation was successful.
* @param {Ext.data.Operation} operation The associated operation
*/
@@ -366,7 +395,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
@@ -379,16 +408,16 @@ Ext.define('Ext.data.Store', {
me.inlineData = data;
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,7 +426,8 @@ 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);
}
@@ -421,16 +451,19 @@ Ext.define('Ext.data.Store', {
// this.load(typeof this.autoLoad == 'object' ? this.autoLoad : undefined);
}
},
-
+
onBeforeSort: function() {
- this.sort(this.groupers.items, 'prepend', false);
+ var groupers = this.groupers;
+ if (groupers.getCount() > 0) {
+ this.sort(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
- * @return {Array} Array of Ext.util.Grouper objects
+ * @param {Object[]} groupers The groupers array
+ * @return {Ext.util.Grouper[]} Array of Ext.util.Grouper objects
*/
decodeGroupers: function(groupers) {
if (!Ext.isArray(groupers)) {
@@ -454,7 +487,7 @@ Ext.define('Ext.data.Store', {
property: config
};
}
-
+
Ext.applyIf(config, {
root : 'data',
direction: "ASC"
@@ -478,18 +511,19 @@ 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},
+ * @param {String/Object[]} 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.
* @param {String} direction The overall direction to group the data by. Defaults to "ASC".
*/
group: function(groupers, direction) {
var me = this,
+ hasNew = false,
grouper,
newGroupers;
-
+
if (Ext.isArray(groupers)) {
newGroupers = groupers;
} else if (Ext.isObject(groupers)) {
@@ -509,25 +543,27 @@ Ext.define('Ext.data.Store', {
grouper.setDirection(direction);
}
}
-
+
if (newGroupers && newGroupers.length) {
+ hasNew = true;
newGroupers = me.decodeGroupers(newGroupers);
me.groupers.clear();
me.groupers.addAll(newGroupers);
}
-
+
if (me.remoteGroup) {
me.load({
scope: me,
callback: me.fireGroupChange
});
} else {
- me.sort();
- me.fireEvent('groupchange', me, me.groupers);
+ // need to explicitly force a sort if we have groupers
+ me.sort(null, null, null, hasNew);
+ me.fireGroupChange();
}
},
-
- /**
+
+ /**
* Clear any groupers in the store
*/
clearGrouping: function(){
@@ -547,29 +583,29 @@ Ext.define('Ext.data.Store', {
me.fireEvent('groupchange', me, me.groupers);
}
},
-
- /**
+
+ /**
* Checks if the store is currently grouped
* @return {Boolean} True if the store is grouped.
*/
isGrouped: function() {
- return this.groupers.getCount() > 0;
+ return this.groupers.getCount() > 0;
},
-
- /**
+
+ /**
* Fires the groupchange event. Abstracted out so we can use it
* as a callback
* @private
*/
fireGroupChange: function(){
- this.fireEvent('groupchange', this, this.groupers);
+ this.fireEvent('groupchange', this, this.groupers);
},
- /**
- * Returns an object containing the result of applying grouping to the records in this store. See {@link #groupField},
+ /**
+ * Returns an array 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>
-var myStore = new Ext.data.Store({
+var myStore = Ext.create('Ext.data.Store', {
groupField: 'color',
groupDir : 'DESC'
});
@@ -591,7 +627,7 @@ myStore.getGroups(); //returns:
]
</code></pre>
* @param {String} groupName (Optional) Pass in an optional groupName argument to access a specific group as defined by {@link #getGroupString}
- * @return {Array} The grouped data
+ * @return {Object/Object[]} The grouped data
*/
getGroups: function(requestGroupString) {
var records = this.data.items,
@@ -624,7 +660,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,14 +695,14 @@ 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
* {@link #getGroupsForGrouper} - this function largely just handles the recursion.
- * @param {Array} records The set or subset of records to group
+ * @param {Ext.data.Model[]} records The set or subset of records to group
* @param {Number} grouperIndex The grouper index to retrieve
- * @return {Array} The grouped records
+ * @return {Object[]} The grouped records
*/
getGroupsForGrouperIndex: function(records, grouperIndex) {
var me = this,
@@ -689,7 +725,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>
@@ -723,7 +759,7 @@ myStore.getGroups(); //returns:
* @param {Boolean} sort True to call {@link #sort} before finding groups. Sorting is required to make grouping
* function correctly so this should only be set to false if the Store is known to already be sorted correctly
* (defaults to true)
- * @return {Array} The group data
+ * @return {Object[]} The group data
*/
getGroupData: function(sort) {
var me = this;
@@ -734,12 +770,12 @@ 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>
<pre><code>
-new Ext.data.Store({
+Ext.create('Ext.data.Store', {
groupDir: 'ASC',
getGroupString: function(instance) {
return instance.get('name')[0];
@@ -756,7 +792,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.
@@ -775,7 +811,7 @@ new Ext.data.Store({
record.set(me.modelDefaults);
// reassign the model in the array in case it wasn't created yet
records[i] = record;
-
+
me.data.insert(index + i, record);
record.join(me);
@@ -793,18 +829,21 @@ 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.
+ /**
+ * 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:
*
-<pre><code>
-myStore.add({some: 'data'}, {some: 'other data'});
-</code></pre>
+ * myStore.add({some: 'data'}, {some: 'other data'});
*
- * @param {Object} data The data for each model
- * @return {Array} The array of newly created model instances
+ * @param {Ext.data.Model[]/Ext.data.Model...} model An array of Model instances
+ * or Model configuration objects, or variable number of Model instance or config arguments.
+ * @return {Ext.data.Model[]} The model instances that were added
*/
add: function(records) {
//accept both a single-argument array of records, or any number of record arguments
@@ -828,7 +867,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 +881,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,10 +892,10 @@ 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
+ * @param {Ext.data.Model/Ext.data.Model[]} records The Ext.data.Model instance or array of instances to remove
*/
remove: function(records, /* private */ isMove) {
if (!Ext.isArray(records)) {
@@ -878,11 +917,11 @@ myStore.add({some: 'data'}, {some: 'other data'});
for (; i < length; i++) {
record = records[i];
index = me.data.indexOf(record);
-
+
if (me.snapshot) {
me.snapshot.remove(record);
}
-
+
if (index > -1) {
isPhantom = record.phantom === true;
if (!isMove && !isPhantom) {
@@ -904,7 +943,7 @@ myStore.add({some: 'data'}, {some: 'other data'});
}
},
- /**
+ /**
* Removes the model instance at the given index
* @param {Number} index The record index
*/
@@ -916,7 +955,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>
@@ -939,11 +978,11 @@ store.load(function(records, operation, success) {
});
</code></pre>
*
- * @param {Object/Function} options Optional config object, passed into the Ext.data.Operation object before loading.
+ * @param {Object/Function} options (Optional) config object, passed into the Ext.data.Operation object before loading.
*/
load: function(options) {
var me = this;
-
+
options = options || {};
if (Ext.isFunction(options)) {
@@ -958,12 +997,12 @@ store.load(function(records, operation, success) {
start: (me.currentPage - 1) * me.pageSize,
limit: me.pageSize,
addRecords: false
- });
+ });
return me.callParent([options]);
},
- /**
+ /**
* @private
* Called internally when a Proxy has completed a load request
*/
@@ -991,11 +1030,11 @@ store.load(function(records, operation, success) {
//this is a callback that would have been passed to the 'read' function and is optional
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
+ * @param {Ext.data.Model[]} records The array of new records
* @param {Ext.data.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
@@ -1010,8 +1049,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,10 +1077,10 @@ 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
+ * @param {Ext.data.Model[]} records The array of updated records
* @param {Ext.data.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
@@ -1064,10 +1103,10 @@ 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
+ * @param {Ext.data.Model[]} records The array of removed records
* @param {Ext.data.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
@@ -1102,13 +1141,33 @@ 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,
+ *
+ * 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 {@link Ext.util.Filter#root 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'})
+ * ]);
+ *
+ * @param {Object[]/Ext.util.Filter[]/String} 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
* MixedCollection's {@link Ext.util.MixedCollection#filter filter} method for filter syntax. Alternatively,
* pass in a property string
- * @param {String} value Optional value to filter by (only if using a property string as the first argument)
+ * @param {String} value (optional) value to filter by (only if using a property string as the first argument)
*/
filter: function(filters, value) {
if (Ext.isString(filters)) {
@@ -1132,7 +1191,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 +1212,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 +1234,7 @@ store.load(function(records, operation, success) {
}
},
- /**
+ /**
* Returns true if this store is currently filtered
* @return {Boolean}
*/
@@ -1184,7 +1243,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 +1262,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.
@@ -1213,7 +1272,7 @@ store.load(function(records, operation, success) {
* <li><b>id</b> : Object<p class="sub-desc">The ID of the Record passed.</p></li>
* </ul>
* @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to this Store.
- * @return {MixedCollection} Returns an Ext.util.MixedCollection of the matched records
+ * @return {Ext.util.MixedCollection} Returns an Ext.util.MixedCollection of the matched records
**/
queryBy: function(fn, scope) {
var me = this,
@@ -1221,14 +1280,22 @@ 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
+ /**
+ * 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
+ * {@link Ext.data.proxy.Memory MemoryProxy} instead.
+ *
+ * @param {Ext.data.Model[]/Object[]} data Array of data to load. Any non-model instances will be cast
+ * into model instances.
+ * @param {Boolean} [append=false] True to add the records to the existing records in the store, false
+ * to remove the old ones first.
*/
loadData: function(data, append) {
var model = this.model,
length = data.length,
+ newData = [],
i,
record;
@@ -1236,18 +1303,41 @@ store.load(function(records, operation, success) {
for (i = 0; i < length; i++) {
record = data[i];
- if (! (record instanceof Ext.data.Model)) {
- data[i] = Ext.ModelManager.create(record, model);
+ if (!(record instanceof Ext.data.Model)) {
+ record = Ext.ModelManager.create(record, model);
}
+ newData.push(record);
}
- this.loadRecords(data, {addRecords: append});
+ this.loadRecords(newData, {addRecords: append});
},
- /**
- * Loads an array of {@Ext.data.Model model} instances into the store, fires the datachanged event. This should only usually
+
+ /**
+ * 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.
+ *
+ * @param {Object[]} data The full JSON object you'd like to load into the Data store.
+ * @param {Boolean} [append=false] True to add the records to the existing records in the store, false
+ * to remove the old ones first.
+ */
+ loadRawData : function(data, append) {
+ var me = this,
+ result = me.proxy.reader.read(data),
+ records = result.records;
+
+ if (result.success) {
+ me.loadRecords(records, { addRecords: append });
+ me.fireEvent('load', me, records, true);
+ }
+ },
+
+
+ /**
+ * Loads an array of {@link 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
+ * @param {Ext.data.Model[]} records The array of records to load
* @param {Object} options {addRecords: true} to add these records to the existing records, false to remove the Store's existing records first
*/
loadRecords: function(records, options) {
@@ -1260,7 +1350,7 @@ store.load(function(records, operation, success) {
if (!options.addRecords) {
delete me.snapshot;
- me.data.clear();
+ me.clearData();
}
me.data.addAll(records);
@@ -1294,51 +1384,56 @@ 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
+ * @param {Object} options See options for {@link #load}
*/
- loadPage: function(page) {
+ loadPage: function(page, options) {
var me = this;
+ options = Ext.apply({}, options);
me.currentPage = page;
- me.read({
+ me.read(Ext.applyIf(options, {
page: page,
start: (page - 1) * me.pageSize,
limit: me.pageSize,
addRecords: !me.clearOnPageLoad
- });
+ }));
},
- /**
+ /**
* Loads the next 'page' in the current data set
+ * @param {Object} options See options for {@link #load}
*/
- nextPage: function() {
- this.loadPage(this.currentPage + 1);
+ nextPage: function(options) {
+ this.loadPage(this.currentPage + 1, options);
},
- /**
+ /**
* Loads the previous 'page' in the current data set
+ * @param {Object} options See options for {@link #load}
*/
- previousPage: function() {
- this.loadPage(this.currentPage - 1);
+ previousPage: function(options) {
+ this.loadPage(this.currentPage - 1, options);
},
// private
clearData: function() {
- this.data.each(function(record) {
- record.unjoin();
+ var me = this;
+ me.data.each(function(record) {
+ record.unjoin(me);
});
- this.data.clear();
+ me.data.clear();
},
-
+
// 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.
+ /**
+ * Prefetches data into 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}
*/
prefetch: function(options) {
@@ -1366,24 +1461,23 @@ store.load(function(records, operation, success) {
me.loading = true;
me.proxy.read(operation, me.onProxyPrefetch, me);
}
-
+
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.
+ * @param {Object} options (Optional) config object, passed into the Ext.data.Operation object before loading.
* See {@link #load}
- * @param
*/
prefetchPage: function(page, options) {
var me = this,
pageSize = me.pageSize,
start = (page - 1) * me.pageSize,
end = start + pageSize;
-
- // Currently not requesting this page and range isn't already satisified
+
+ // Currently not requesting this page and range isn't already satisified
if (Ext.Array.indexOf(me.pagesRequested, page) === -1 && !me.rangeSatisfied(start, end)) {
options = options || {};
me.pagesRequested.push(page);
@@ -1394,13 +1488,13 @@ store.load(function(records, operation, success) {
callback: me.onWaitForGuarantee,
scope: me
});
-
+
me.prefetch(options);
}
-
+
},
-
- /**
+
+ /**
* Returns a unique requestId to track requests.
* @private
*/
@@ -1408,9 +1502,9 @@ store.load(function(records, operation, success) {
this.requestSeed = this.requestSeed || 1;
return this.requestSeed++;
},
-
- /**
- * Handles a success pre-fetch
+
+ /**
+ * Called after the configured proxy completes a prefetch operation.
* @private
* @param {Ext.data.Operation} operation The operation that completed
*/
@@ -1418,14 +1512,14 @@ store.load(function(records, operation, success) {
var me = this,
resultSet = operation.getResultSet(),
records = operation.getRecords(),
-
+
successful = operation.wasSuccessful();
-
+
if (resultSet) {
me.totalCount = resultSet.total;
me.fireEvent('totalcountchange', me.totalCount);
}
-
+
if (successful) {
me.cacheRecords(records, operation);
}
@@ -1433,10 +1527,10 @@ store.load(function(records, operation, success) {
if (operation.page) {
Ext.Array.remove(me.pagesRequested, operation.page);
}
-
+
me.loading = false;
me.fireEvent('prefetch', me, records, successful, operation);
-
+
// HACK to support loadMask
if (operation.blocking) {
me.fireEvent('load', me, records, successful);
@@ -1445,12 +1539,12 @@ store.load(function(records, operation, success) {
//this is a callback that would have been passed to the 'read' function and is optional
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
- * @param {Array} records The records to cache
+ * @param {Ext.data.Model[]} records The records to cache
* @param {Ext.data.Operation} The associated operation
*/
cacheRecords: function(records, operation) {
@@ -1458,26 +1552,26 @@ store.load(function(records, operation, success) {
i = 0,
length = records.length,
start = operation ? operation.start : 0;
-
+
if (!Ext.isDefined(me.totalCount)) {
me.totalCount = records.length;
me.fireEvent('totalcountchange', me.totalCount);
}
-
+
for (; i < length; i++) {
// this is the true index, not the viewIndex
records[i].index = start + i;
}
-
+
me.prefetchData.addAll(records);
if (me.purgePageCount) {
me.purgeRecords();
}
-
+
},
-
-
- /**
+
+
+ /**
* Purge the least recently used records in the prefetch if the purgeCount
* has been exceeded.
*/
@@ -1492,8 +1586,8 @@ store.load(function(records, operation, success) {
me.prefetchData.removeAt(0);
}
},
-
- /**
+
+ /**
* Determines if the range has already been satisfied in the prefetchData.
* @private
* @param {Number} start The start index
@@ -1517,8 +1611,8 @@ 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
@@ -1526,8 +1620,8 @@ store.load(function(records, operation, success) {
getPageFromRecordIndex: function(index) {
return Math.floor(index / this.pageSize) + 1;
},
-
- /**
+
+ /**
* Handles a guaranteed range being loaded
* @private
*/
@@ -1539,64 +1633,73 @@ store.load(function(records, operation, success) {
range = [],
record,
i = start;
-
+
+ end = Math.max(0, end);
+
//<debug>
if (start > end) {
- Ext.Error.raise("Start (" + start + ") was greater than end (" + end + ")");
+ Ext.log({
+ level: 'warn',
+ msg: 'Start (' + start + ') was greater than end (' + end +
+ ') for the range of records requested (' + me.requestStart + '-' +
+ me.requestEnd + ')' + (this.storeId ? ' from store "' + this.storeId + '"' : '')
+ });
}
//</debug>
-
+
if (start !== me.guaranteedStart && end !== me.guaranteedEnd) {
me.guaranteedStart = start;
me.guaranteedEnd = end;
-
+
for (; i <= end; i++) {
record = me.prefetchData.getByKey(i);
//<debug>
- if (!record) {
- Ext.Error.raise("Record was not found and store said it was guaranteed");
- }
+// if (!record) {
+// Ext.log('Record with key "' + i + '" was not found and store said it was guaranteed');
+// }
//</debug>
- range.push(record);
+ if (record) {
+ range.push(record);
+ }
}
me.fireEvent('guaranteedrange', range, start, end);
if (me.cb) {
me.cb.call(me.scope || me, range);
}
}
-
+
me.unmask();
},
-
+
// hack to support loadmask
mask: function() {
this.masked = true;
this.fireEvent('beforeload');
},
-
+
// hack to support loadmask
unmask: function() {
if (this.masked) {
this.fireEvent('load');
}
},
-
- /**
+
+ /**
* Returns the number of pending requests out.
*/
hasPendingRequests: function() {
return this.pendingRequests.length;
},
-
-
+
+
// wait until all requests finish, until guaranteeing the range.
onWaitForGuarantee: function() {
if (!this.hasPendingRequests()) {
this.onGuaranteedRange();
}
},
-
- /**
+
+ /**
* 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.
@@ -1614,9 +1717,9 @@ store.load(function(records, operation, success) {
}
}
//</debug>
-
+
end = (end > this.totalCount) ? this.totalCount - 1 : end;
-
+
var me = this,
i = start,
prefetchData = me.prefetchData,
@@ -1625,7 +1728,7 @@ store.load(function(records, operation, success) {
endLoaded = !!prefetchData.getByKey(end),
startPage = me.getPageFromRecordIndex(start),
endPage = me.getPageFromRecordIndex(end);
-
+
me.cb = cb;
me.scope = scope;
@@ -1660,7 +1763,7 @@ store.load(function(records, operation, success) {
me.onGuaranteedRange();
}
},
-
+
// because prefetchData is stored by index
// this invalidates all of the prefetchedData
sort: function() {
@@ -1670,7 +1773,7 @@ store.load(function(records, operation, success) {
start,
end,
range;
-
+
if (me.buffered) {
if (me.remoteSort) {
prefetchData.clear();
@@ -1679,8 +1782,7 @@ store.load(function(records, operation, success) {
sorters = me.getSorters();
start = me.guaranteedStart;
end = me.guaranteedEnd;
- range;
-
+
if (sorters.length) {
prefetchData.sort(sorters);
range = prefetchData.getRange();
@@ -1718,8 +1820,8 @@ store.load(function(records, operation, success) {
me.fireEvent('datachanged', me);
}
},
-
- /**
+
+ /**
* 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
@@ -1727,7 +1829,7 @@ store.load(function(records, operation, success) {
* @param {Number} startIndex (optional) The index to start searching at
* @param {Boolean} anyMatch (optional) True to match any part of the string, not just the beginning
* @param {Boolean} caseSensitive (optional) True for case sensitive comparison
- * @param {Boolean} exactMatch True to force exact match (^ and $ characters added to the regex). Defaults to false.
+ * @param {Boolean} exactMatch (optional) True to force exact match (^ and $ characters added to the regex). Defaults to false.
* @return {Number} The matched index or -1
*/
find: function(property, value, start, anyMatch, caseSensitive, exactMatch) {
@@ -1735,7 +1837,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
@@ -1743,7 +1845,7 @@ store.load(function(records, operation, success) {
* @param {Number} startIndex (optional) The index to start searching at
* @param {Boolean} anyMatch (optional) True to match any part of the string, not just the beginning
* @param {Boolean} caseSensitive (optional) True for case sensitive comparison
- * @param {Boolean} exactMatch True to force exact match (^ and $ characters added to the regex). Defaults to false.
+ * @param {Boolean} exactMatch (optional) True to force exact match (^ and $ characters added to the regex). Defaults to false.
* @return {Ext.data.Model} The matched record or null
*/
findRecord: function() {
@@ -1752,15 +1854,15 @@ 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
* @param {String} property The property to create the filter function for
* @param {String/RegExp} value The string/regex to compare the property value to
- * @param {Boolean} anyMatch True if we don't care if the filter value is not the full value (defaults to false)
- * @param {Boolean} caseSensitive True to create a case-sensitive regex (defaults to false)
- * @param {Boolean} exactMatch True to force exact match (^ and $ characters added to the regex). Defaults to false.
+ * @param {Boolean} [anyMatch=false] True if we don't care if the filter value is not the full value.
+ * @param {Boolean} [caseSensitive=false] True to create a case-sensitive regex.
+ * @param {Boolean} [exactMatch=false] True to force exact match (^ and $ characters added to the regex).
* Ignored if anyMatch is true.
*/
createFilterFn: function(property, value, anyMatch, caseSensitive, exactMatch) {
@@ -1773,21 +1875,21 @@ 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.
+ * @param {Object} value The value to match the field against.
* @param {Number} startIndex (optional) The index to start searching at
* @return {Number} The matched index or -1
*/
findExact: function(property, value, start) {
return this.data.findIndexBy(function(rec) {
- return rec.get(property) === value;
+ return rec.get(property) == value;
},
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,12 +1905,12 @@ 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
* @param {Boolean} bypassFilter (optional) Pass true to collect from all records, even ones which are filtered
- * @return {Array} An array of the unique values
+ * @return {Object[]} An array of the unique values
**/
collect: function(dataIndex, allowNull, bypassFilter) {
var me = this,
@@ -1817,7 +1919,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 +1930,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 +1941,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,20 +1950,20 @@ 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)
+ * @param {Number} [startIndex=0] The starting index
+ * @param {Number} [endIndex] The ending index. Defaults to the last Record in the Store.
* @return {Ext.data.Model[]} An array of Records
*/
getRange: function(start, end) {
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.
+ * @return {Ext.data.Model} The Record with the passed id. Returns null if not found.
*/
getById: function(id) {
return (this.snapshot || this.data).findBy(function(record) {
@@ -1869,7 +1971,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,25 +1981,29 @@ 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.
*/
indexOfTotal: function(record) {
- return record.index || this.indexOf(record);
+ var index = record.index;
+ if (index || index === 0) {
+ return index;
+ }
+ return 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.
*/
indexOfId: function(id) {
- return this.data.indexOfKey(id);
+ return this.indexOf(this.getById(id));
},
-
- /**
+
+ /**
* Remove all items from the store.
* @param {Boolean} silent Prevent the `clear` event from being fired.
*/
@@ -1917,7 +2023,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 +2043,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 +2064,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 +2097,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,14 +2117,14 @@ 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
* in the store. The value returned will be an object literal with the key being the group
* name and the minimum in the group being the value. The grouped parameter is only honored if
* the store has a groupField.
- * @return {Mixed/undefined} The minimum value, if no items exist, undefined.
+ * @return {Object} The minimum value, if no items exist, undefined.
*/
min: function(field, grouped) {
var me = this;
@@ -2049,14 +2155,14 @@ 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
* in the store. The value returned will be an object literal with the key being the group
* name and the maximum in the group being the value. The grouped parameter is only honored if
* the store has a groupField.
- * @return {Mixed/undefined} The maximum value, if no items exist, undefined.
+ * @return {Object} The maximum value, if no items exist, undefined.
*/
max: function(field, grouped) {
var me = this;
@@ -2088,14 +2194,14 @@ 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
* in the store. The value returned will be an object literal with the key being the group
* name and the group average being the value. The grouped parameter is only honored if
* the store has a groupField.
- * @return {Mixed/undefined} The average value, if no items exist, 0.
+ * @return {Object} The average value, if no items exist, 0.
*/
average: function(field, grouped) {
var me = this;
@@ -2121,7 +2227,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.
@@ -2151,5 +2257,12 @@ store.load(function(records, operation, success) {
return fn.apply(scope || this, [this.data.items].concat(args));
}
}
+}, function() {
+ // A dummy empty store with a fieldless Model defined in it.
+ // Just for binding to Views which are instantiated with no Store defined.
+ // They will be able to run and render fine, and be bound to a generated Store later.
+ Ext.regStore('ext-empty-store', {fields: [], proxy: 'proxy'});
});
-