/**
* @author Ed Spencer
* @class Ext.data.Store
* @extends Ext.data.AbstractStore
*
* <p>The Store class encapsulates a client side cache of {@link Ext.data.Model Model} objects. Stores load
* data via a {@link Ext.data.proxy.Proxy Proxy}, and also provide functions for {@link #sort sorting},
* {@link #filter filtering} and querying the {@link Ext.data.Model model} instances contained within it.</p>
*
* <p>Creating a Store is easy - we just tell it the Model and the Proxy to use to load and save its data:</p>
*
<pre><code>
// Set up a {@link Ext.data.Model model} to use in our Store
Ext.define('User', {
extend: 'Ext.data.Model',
fields: [
{name: 'firstName', type: 'string'},
{name: 'lastName', type: 'string'},
{name: 'age', type: 'int'},
{name: 'eyeColor', type: 'string'}
]
});
var myStore = new Ext.data.Store({
model: 'User',
proxy: {
type: 'ajax',
url : '/users.json',
reader: {
type: 'json',
root: 'users'
}
},
autoLoad: true
});
</code></pre>
* <p>In the example above we configured an AJAX proxy to load data from the url '/users.json'. We told our Proxy
* to use a {@link Ext.data.reader.Json JsonReader} to parse the response from the server into Model object -
* {@link Ext.data.reader.Json see the docs on JsonReader} for details.</p>
*
* <p><u>Inline data</u></p>
*
* <p>Stores can also load data inline. Internally, Store converts each of the objects we pass in as {@link #data}
* into Model instances:</p>
*
<pre><code>
new Ext.data.Store({
model: 'User',
data : [
{firstName: 'Ed', lastName: 'Spencer'},
{firstName: 'Tommy', lastName: 'Maintz'},
{firstName: 'Aaron', lastName: 'Conran'},
{firstName: 'Jamie', lastName: 'Avins'}
]
});
</code></pre>
*
* <p>Loading inline data using the method above is great if the data is in the correct format already (e.g. it doesn't need
* to be processed by a {@link Ext.data.reader.Reader reader}). If your inline data requires processing to decode the data structure,
* use a {@link Ext.data.proxy.Memory MemoryProxy} instead (see the {@link Ext.data.proxy.Memory MemoryProxy} docs for an example).</p>
*
* <p>Additional data can also be loaded locally using {@link #add}.</p>
*
* <p><u>Loading Nested Data</u></p>
*
* <p>Applications often need to load sets of associated data - for example a CRM system might load a User and her Orders.
* Instead of issuing an AJAX request for the User and a series of additional AJAX requests for each Order, we can load a nested dataset
* and allow the Reader to automatically populate the associated models. Below is a brief example, see the {@link Ext.data.reader.Reader} intro
* docs for a full explanation:</p>
*
<pre><code>
var store = new Ext.data.Store({
autoLoad: true,
model: "User",
proxy: {
type: 'ajax',
url : 'users.json',
reader: {
type: 'json',
root: 'users'
}
}
});
</code></pre>
*
* <p>Which would consume a response like this:</p>
*
<pre><code>
{
"users": [
{
"id": 1,
"name": "Ed",
"orders": [
{
"id": 10,
"total": 10.76,
"status": "invoiced"
},
{
"id": 11,
"total": 13.45,
"status": "shipped"
}
]
}
]
}
</code></pre>
*
* <p>See the {@link Ext.data.reader.Reader} intro docs for a full explanation.</p>
*
* <p><u>Filtering and Sorting</u></p>
*
* <p>Stores can be sorted and filtered - in both cases either remotely or locally. The {@link #sorters} and {@link #filters} are
* held inside {@link Ext.util.MixedCollection MixedCollection} instances to make them easy to manage. Usually it is sufficient to
* either just specify sorters and filters in the Store configuration or call {@link #sort} or {@link #filter}:
*
<pre><code>
var store = new Ext.data.Store({
model: 'User',
sorters: [
{
property : 'age',
direction: 'DESC'
},
{
property : 'firstName',
direction: 'ASC'
}
],
filters: [
{
property: 'firstName',
value : /Ed/
}
]
});
</code></pre>
*
* <p>The new Store will keep the configured sorters and filters in the MixedCollection instances mentioned above. By default, sorting
* and filtering are both performed locally by the Store - see {@link #remoteSort} and {@link #remoteFilter} to allow the server to
* perform these operations instead.</p>
*
* <p>Filtering and sorting after the Store has been instantiated is also easy. Calling {@link #filter} adds another filter to the Store
* and automatically filters the dataset (calling {@link #filter} with no arguments simply re-applies all existing filters). Note that by
* default {@link #sortOnFilter} is set to true, which means that your sorters are automatically reapplied if using local sorting.</p>
*
<pre><code>
store.filter('eyeColor', 'Brown');
</code></pre>
*
* <p>Change the sorting at any time by calling {@link #sort}:</p>
*
<pre><code>
store.sort('height', 'ASC');
</code></pre>
*
* <p>Note that all existing sorters will be removed in favor of the new sorter data (if {@link #sort} is called with no arguments,
* the existing sorters are just reapplied instead of being removed). To keep existing sorters and add new ones, just add them
* to the MixedCollection:</p>
*
<pre><code>
store.sorters.add(new Ext.util.Sorter({
property : 'shoeSize',
direction: 'ASC'
}));
store.sort();
</code></pre>
*
* <p><u>Registering with StoreManager</u></p>
*
* <p>Any Store that is instantiated with a {@link #storeId} will automatically be registed with the {@link Ext.data.StoreManager StoreManager}.
* This makes it easy to reuse the same store in multiple views:</p>
*
<pre><code>
//this store can be used several times
new Ext.data.Store({
model: 'User',
storeId: 'usersStore'
});
new Ext.List({
store: 'usersStore',
//other config goes here
});
new Ext.view.View({
store: 'usersStore',
//other config goes here
});
</code></pre>
*
* <p><u>Further Reading</u></p>
*
* <p>Stores are backed up by an ecosystem of classes that enables their operation. To gain a full understanding of these
* pieces and how they fit together, see:</p>
*
* <ul style="list-style-type: disc; padding-left: 25px">
* <li>{@link Ext.data.proxy.Proxy Proxy} - overview of what Proxies are and how they are used</li>
* <li>{@link Ext.data.Model Model} - the core class in the data package</li>
* <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'],
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
* 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
*/
/**
* 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.
* @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
* 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
* @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
* 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.
*/
purgePageCount: 5,
isStore: true,
//documented above
constructor: function(config) {
config = config || {};
var me = this,
groupers = config.groupers,
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.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
* @param {Array} records An array of records
* @param {Boolean} successful True if the operation was successful.
* @param {Ext.data.Operation} operation The associated operation
*/
'prefetch'
);
data = config.data || me.data;
/**
* The MixedCollection that holds this store's local cache of records
* @property data
* @type Ext.util.MixedCollection
*/
me.data = Ext.create('Ext.util.MixedCollection', false, function(record) {
return record.internalId;
});
if (data) {
me.inlineData = data;
delete config.data;
}
if (!groupers && config.groupField) {
groupers = [{
property : config.groupField,
direction: config.groupDir
}];
}
delete config.groupers;
/**
* The collection of {@link Ext.util.Grouper Groupers} currently applied to this Store
* @property groupers
* @type Ext.util.MixedCollection
*/
me.groupers = Ext.create('Ext.util.MixedCollection');
me.groupers.addAll(me.decodeGroupers(groupers));
this.callParent([config]);
if (me.groupers.items.length) {
me.sort(me.groupers.items, 'prepend', false);
}
proxy = me.proxy;
data = me.inlineData;
if (data) {
if (proxy instanceof Ext.data.proxy.Memory) {
proxy.data = data;
me.read();
} else {
me.add.apply(me, data);
}
me.sort();
delete me.inlineData;
} else if (me.autoLoad) {
Ext.defer(me.load, 10, me, [typeof me.autoLoad === 'object' ? me.autoLoad: undefined]);
// Remove the defer call, we may need reinstate this at some point, but currently it's not obvious why it's here.
// this.load(typeof this.autoLoad == 'object' ? this.autoLoad : undefined);
}
},
onBeforeSort: function() {
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
* @return {Array} Array of Ext.util.Grouper objects
*/
decodeGroupers: function(groupers) {
if (!Ext.isArray(groupers)) {
if (groupers === undefined) {
groupers = [];
} else {
groupers = [groupers];
}
}
var length = groupers.length,
Grouper = Ext.util.Grouper,
config, i;
for (i = 0; i < length; i++) {
config = groupers[i];
if (!(config instanceof Grouper)) {
if (Ext.isString(config)) {
config = {
property: config
};
}
Ext.applyIf(config, {
root : 'data',
direction: "ASC"
});
//support for 3.x style sorters where a function can be defined as 'fn'
if (config.fn) {
config.sorterFn = config.fn;
}
//support a function to be passed as a sorter definition
if (typeof config == 'function') {
config = {
sorterFn: config
};
}
groupers[i] = new Grouper(config);
}
}
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.
* @param {String} direction The overall direction to group the data by. Defaults to "ASC".
*/
group: function(groupers, direction) {
var me = this,
grouper,
newGroupers;
if (Ext.isArray(groupers)) {
newGroupers = groupers;
} else if (Ext.isObject(groupers)) {
newGroupers = [groupers];
} else if (Ext.isString(groupers)) {
grouper = me.groupers.get(groupers);
if (!grouper) {
grouper = {
property : groupers,
direction: direction
};
newGroupers = [grouper];
} else if (direction === undefined) {
grouper.toggle();
} else {
grouper.setDirection(direction);
}
}
if (newGroupers && newGroupers.length) {
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);
}
},
/**
* Clear any groupers in the store
*/
clearGrouping: function(){
var me = this;
// Clear any groupers we pushed on to the sorters
me.groupers.each(function(grouper){
me.sorters.remove(grouper);
});
me.groupers.clear();
if (me.remoteGroup) {
me.load({
scope: me,
callback: me.fireGroupChange
});
} else {
me.sort();
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;
},
/**
* Fires the groupchange event. Abstracted out so we can use it
* as a callback
* @private
*/
fireGroupChange: function(){
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>
var myStore = new Ext.data.Store({
groupField: 'color',
groupDir : 'DESC'
});
myStore.getGroups(); //returns:
[
{
name: 'yellow',
children: [
//all records where the color field is 'yellow'
]
},
{
name: 'red',
children: [
//all records where the color field is 'red'
]
}
]
</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
*/
getGroups: function(requestGroupString) {
var records = this.data.items,
length = records.length,
groups = [],
pointers = {},
record,
groupStr,
group,
i;
for (i = 0; i < length; i++) {
record = records[i];
groupStr = this.getGroupString(record);
group = pointers[groupStr];
if (group === undefined) {
group = {
name: groupStr,
children: []
};
groups.push(group);
pointers[groupStr] = group;
}
group.children.push(record);
}
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.
*/
getGroupsForGrouper: function(records, grouper) {
var length = records.length,
groups = [],
oldValue,
newValue,
record,
group,
i;
for (i = 0; i < length; i++) {
record = records[i];
newValue = grouper.getGroupString(record);
if (newValue !== oldValue) {
group = {
name: newValue,
grouper: grouper,
records: []
};
groups.push(group);
}
group.records.push(record);
oldValue = newValue;
}
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 {Number} grouperIndex The grouper index to retrieve
* @return {Array} The grouped records
*/
getGroupsForGrouperIndex: function(records, grouperIndex) {
var me = this,
groupers = me.groupers,
grouper = groupers.getAt(grouperIndex),
groups = me.getGroupsForGrouper(records, grouper),
length = groups.length,
i;
if (grouperIndex + 1 < groupers.length) {
for (i = 0; i < length; i++) {
groups[i].children = me.getGroupsForGrouperIndex(groups[i].records, grouperIndex + 1);
}
}
for (i = 0; i < length; i++) {
groups[i].depth = grouperIndex;
}
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>
<pre><code>
[
{
name: 'Fantasy',
depth: 0,
records: [
//book1, book2, book3, book4
],
children: [
{
name: 'Rowling',
depth: 1,
records: [
//book1, book2
]
},
{
name: 'Tolkein',
depth: 1,
records: [
//book3, book4
]
}
]
}
]
</code></pre>
* @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
*/
getGroupData: function(sort) {
var me = this;
if (sort !== false) {
me.sort();
}
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({
groupDir: 'ASC',
getGroupString: function(instance) {
return instance.get('name')[0];
}
});
</code></pre>
* @param {Ext.data.Model} instance The model instance
* @return {String} The string to compare when forming groups
*/
getGroupString: function(instance) {
var group = this.groupers.first();
if (group) {
return instance.get(group.property);
}
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.
* @param {Ext.data.Model[]} records An Array of Ext.data.Model objects to add to the cache.
*/
insert: function(index, records) {
var me = this,
sync = false,
i,
record,
len;
records = [].concat(records);
for (i = 0, len = records.length; i < len; i++) {
record = me.createModel(records[i]);
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);
sync = sync || record.phantom === true;
}
if (me.snapshot) {
me.snapshot.addAll(records);
}
me.fireEvent('add', me, records, index);
me.fireEvent('datachanged', me);
if (me.autoSync && sync) {
me.sync();
}
},
/**
* 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.
* Sample usage:
*
<pre><code>
myStore.add({some: 'data'}, {some: 'other data'});
</code></pre>
*
* @param {Object} data The data for each model
* @return {Array} The array of newly created model instances
*/
add: function(records) {
//accept both a single-argument array of records, or any number of record arguments
if (!Ext.isArray(records)) {
records = Array.prototype.slice.apply(arguments);
}
var me = this,
i = 0,
length = records.length,
record;
for (; i < length; i++) {
record = me.createModel(records[i]);
// reassign the model in the array in case it wasn't created yet
records[i] = record;
}
me.insert(me.data.length, records);
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
* @return {Ext.data.Model}
*/
createModel: function(record) {
if (!record.isModel) {
record = Ext.ModelManager.create(record, this.model);
}
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.
* @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed.
* Defaults to the current {@link Ext.data.Model Record} in the iteration.
*/
each: function(fn, scope) {
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
*/
remove: function(records, /* private */ isMove) {
if (!Ext.isArray(records)) {
records = [records];
}
/*
* Pass the isMove parameter if we know we're going to be re-inserting this record
*/
isMove = isMove === true;
var me = this,
sync = false,
i = 0,
length = records.length,
isPhantom,
index,
record;
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) {
// don't push phantom records onto removed
me.removed.push(record);
}
record.unjoin(me);
me.data.remove(record);
sync = sync || !isPhantom;
me.fireEvent('remove', me, record, index);
}
}
me.fireEvent('datachanged', me);
if (!isMove && me.autoSync && sync) {
me.sync();
}
},
/**
* Removes the model instance at the given index
* @param {Number} index The record index
*/
removeAt: function(index) {
var record = this.getAt(index);
if (record) {
this.remove(record);
}
},
/**
* <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>
*
<pre><code>
store.load({
scope : this,
callback: function(records, operation, success) {
//the {@link Ext.data.Operation operation} object contains all of the details of the load operation
console.log(records);
}
});
</code></pre>
*
* <p>If the callback scope does not need to be set, a function can simply be passed:</p>
*
<pre><code>
store.load(function(records, operation, success) {
console.log('loaded records');
});
</code></pre>
*
* @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)) {
options = {
callback: options
};
}
Ext.applyIf(options, {
groupers: me.groupers.items,
page: me.currentPage,
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
*/
onProxyLoad: function(operation) {
var me = this,
resultSet = operation.getResultSet(),
records = operation.getRecords(),
successful = operation.wasSuccessful();
if (resultSet) {
me.totalCount = resultSet.total;
}
if (successful) {
me.loadRecords(records, operation);
}
me.loading = false;
me.fireEvent('load', me, records, successful);
//TODO: deprecate this event, it should always have been 'load' instead. 'load' is now documented, 'read' is not.
//People are definitely using this so can't deprecate safely until 2.x
me.fireEvent('read', me, records, operation.wasSuccessful());
//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.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
onCreateRecords: function(records, operation, success) {
if (success) {
var i = 0,
data = this.data,
snapshot = this.snapshot,
length = records.length,
originalRecords = operation.records,
record,
original,
index;
/**
* 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.
*/
for (; i < length; ++i) {
record = records[i];
original = originalRecords[i];
if (original) {
index = data.indexOf(original);
if (index > -1) {
data.removeAt(index);
data.insert(index, record);
}
if (snapshot) {
index = snapshot.indexOf(original);
if (index > -1) {
snapshot.removeAt(index);
snapshot.insert(index, record);
}
}
record.phantom = false;
record.join(this);
}
}
}
},
/**
* Update any records when a write is returned from the server.
* @private
* @param {Array} 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
*/
onUpdateRecords: function(records, operation, success){
if (success) {
var i = 0,
length = records.length,
data = this.data,
snapshot = this.snapshot,
record;
for (; i < length; ++i) {
record = records[i];
data.replace(record);
if (snapshot) {
snapshot.replace(record);
}
record.join(this);
}
}
},
/**
* Remove any records when a write is returned from the server.
* @private
* @param {Array} 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
*/
onDestroyRecords: function(records, operation, success){
if (success) {
var me = this,
i = 0,
length = records.length,
data = me.data,
snapshot = me.snapshot,
record;
for (; i < length; ++i) {
record = records[i];
record.unjoin(me);
data.remove(record);
if (snapshot) {
snapshot.remove(record);
}
}
me.removed = [];
}
},
//inherit docs
getNewRecords: function() {
return this.data.filterBy(this.filterNew).items;
},
//inherit docs
getUpdatedRecords: function() {
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
* 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)
*/
filter: function(filters, value) {
if (Ext.isString(filters)) {
filters = {
property: filters,
value: value
};
}
var me = this,
decoded = me.decodeFilters(filters),
i = 0,
doLocalSort = me.sortOnFilter && !me.remoteSort,
length = decoded.length;
for (; i < length; i++) {
me.filters.replace(decoded[i]);
}
if (me.remoteFilter) {
//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
* @type Ext.util.MixedCollection
*/
if (me.filters.getCount()) {
me.snapshot = me.snapshot || me.data.clone();
me.data = me.data.filter(me.filters.items);
if (doLocalSort) {
me.sort();
}
// fire datachanged event if it hasn't already been fired by doSort
if (!doLocalSort || me.sorters.length < 1) {
me.fireEvent('datachanged', me);
}
}
}
},
/**
* 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.
*/
clearFilter: function(suppressEvent) {
var me = this;
me.filters.clear();
if (me.remoteFilter) {
me.load();
} else if (me.isFiltered()) {
me.data = me.snapshot.clone();
delete me.snapshot;
if (suppressEvent !== true) {
me.fireEvent('datachanged', me);
}
}
},
/**
* Returns true if this store is currently filtered
* @return {Boolean}
*/
isFiltered: function() {
var snapshot = this.snapshot;
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.
* @param {Function} fn The function to be called. It will be passed the following parameters:<ul>
* <li><b>record</b> : Ext.data.Model<p class="sub-desc">The {@link Ext.data.Model record}
* to test for filtering. Access field values using {@link Ext.data.Model#get}.</p></li>
* <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.
*/
filterBy: function(fn, scope) {
var me = this;
me.snapshot = me.snapshot || me.data.clone();
me.data = me.queryBy(fn, scope || me);
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.
* @param {Function} fn The function to be called. It will be passed the following parameters:<ul>
* <li><b>record</b> : Ext.data.Model<p class="sub-desc">The {@link Ext.data.Model record}
* to test for filtering. Access field values using {@link Ext.data.Model#get}.</p></li>
* <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
**/
queryBy: function(fn, scope) {
var me = this,
data = me.snapshot || me.data;
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
*/
loadData: function(data, append) {
var model = this.model,
length = data.length,
i,
record;
//make sure each data element is an Ext.data.Model instance
for (i = 0; i < length; i++) {
record = data[i];
if (! (record instanceof Ext.data.Model)) {
data[i] = Ext.ModelManager.create(record, model);
}
}
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
* @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) {
var me = this,
i = 0,
length = records.length;
options = options || {};
if (!options.addRecords) {
delete me.snapshot;
me.data.clear();
}
me.data.addAll(records);
//FIXME: this is not a good solution. Ed Spencer is totally responsible for this and should be forced to fix it immediately.
for (; i < length; i++) {
if (options.start !== undefined) {
records[i].index = options.start + i;
}
records[i].join(me);
}
/*
* this rather inelegant suspension and resumption of events is required because both the filter and sort functions
* fire an additional datachanged event, which is not wanted. Ideally we would do this a different way. The first
* datachanged event is fired by the call to this.add, above.
*/
me.suspendEvents();
if (me.filterOnLoad && !me.remoteFilter) {
me.filter();
}
if (me.sortOnLoad && !me.remoteSort) {
me.sort();
}
me.resumeEvents();
me.fireEvent('datachanged', me, records);
},
// 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
*/
loadPage: function(page) {
var me = this;
me.currentPage = page;
me.read({
page: page,
start: (page - 1) * me.pageSize,
limit: me.pageSize,
addRecords: !me.clearOnPageLoad
});
},
/**
* 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() {
this.loadPage(this.currentPage - 1);
},
// private
clearData: function() {
this.data.each(function(record) {
record.unjoin();
});
this.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.
* See {@link #load}
*/
prefetch: function(options) {
var me = this,
operation,
requestId = me.getRequestId();
options = options || {};
Ext.applyIf(options, {
action : 'read',
filters: me.filters.items,
sorters: me.sorters.items,
requestId: requestId
});
me.pendingRequests.push(requestId);
operation = Ext.create('Ext.data.Operation', options);
// HACK to implement loadMask support.
//if (operation.blocking) {
// me.fireEvent('beforeload', me, operation);
//}
if (me.fireEvent('beforeprefetch', me, operation) !== false) {
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.
* 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
if (Ext.Array.indexOf(me.pagesRequested, page) === -1 && !me.rangeSatisfied(start, end)) {
options = options || {};
me.pagesRequested.push(page);
Ext.applyIf(options, {
page : page,
start: start,
limit: pageSize,
callback: me.onWaitForGuarantee,
scope: me
});
me.prefetch(options);
}
},
/**
* Returns a unique requestId to track requests.
* @private
*/
getRequestId: function() {
this.requestSeed = this.requestSeed || 1;
return this.requestSeed++;
},
/**
* Handles a success pre-fetch
* @private
* @param {Ext.data.Operation} operation The operation that completed
*/
onProxyPrefetch: function(operation) {
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);
}
Ext.Array.remove(me.pendingRequests, operation.requestId);
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);
}
//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.Operation} The associated operation
*/
cacheRecords: function(records, operation) {
var me = this,
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.
*/
purgeRecords: function() {
var me = this,
prefetchCount = me.prefetchData.getCount(),
purgeCount = me.purgePageCount * me.pageSize,
numRecordsToPurge = prefetchCount - purgeCount - 1,
i = 0;
for (; i <= numRecordsToPurge; i++) {
me.prefetchData.removeAt(0);
}
},
/**
* Determines if the range has already been satisfied in the prefetchData.
* @private
* @param {Number} start The start index
* @param {Number} end The end index in the range
*/
rangeSatisfied: function(start, end) {
var me = this,
i = start,
satisfied = true;
for (; i < end; i++) {
if (!me.prefetchData.getByKey(i)) {
satisfied = false;
//<debug>
if (end - i > me.pageSize) {
Ext.Error.raise("A single page prefetch could never satisfy this request.");
}
//</debug>
break;
}
}
return satisfied;
},
/**
* Determines the page from a record index
* @param {Number} index The record index
* @return {Number} The page the record belongs to
*/
getPageFromRecordIndex: function(index) {
return Math.floor(index / this.pageSize) + 1;
},
/**
* Handles a guaranteed range being loaded
* @private
*/
onGuaranteedRange: function() {
var me = this,
totalCount = me.getTotalCount(),
start = me.requestStart,
end = ((totalCount - 1) < me.requestEnd) ? totalCount - 1 : me.requestEnd,
range = [],
record,
i = start;
//<debug>
if (start > end) {
Ext.Error.raise("Start (" + start + ") was greater than end (" + end + ")");
}
//</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");
}
//</debug>
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.
*/
guaranteeRange: function(start, end, cb, scope) {
//<debug>
if (start && end) {
if (end - start > this.pageSize) {
Ext.Error.raise({
start: start,
end: end,
pageSize: this.pageSize,
msg: "Requested a bigger range than the specified pageSize"
});
}
}
//</debug>
end = (end > this.totalCount) ? this.totalCount - 1 : end;
var me = this,
i = start,
prefetchData = me.prefetchData,
range = [],
startLoaded = !!prefetchData.getByKey(start),
endLoaded = !!prefetchData.getByKey(end),
startPage = me.getPageFromRecordIndex(start),
endPage = me.getPageFromRecordIndex(end);
me.cb = cb;
me.scope = scope;
me.requestStart = start;
me.requestEnd = end;
// neither beginning or end are loaded
if (!startLoaded || !endLoaded) {
// same page, lets load it
if (startPage === endPage) {
me.mask();
me.prefetchPage(startPage, {
//blocking: true,
callback: me.onWaitForGuarantee,
scope: me
});
// need to load two pages
} else {
me.mask();
me.prefetchPage(startPage, {
//blocking: true,
callback: me.onWaitForGuarantee,
scope: me
});
me.prefetchPage(endPage, {
//blocking: true,
callback: me.onWaitForGuarantee,
scope: me
});
}
// Request was already satisfied via the prefetch
} else {
me.onGuaranteedRange();
}
},
// because prefetchData is stored by index
// this invalidates all of the prefetchedData
sort: function() {
var me = this,
prefetchData = me.prefetchData,
sorters,
start,
end,
range;
if (me.buffered) {
if (me.remoteSort) {
prefetchData.clear();
me.callParent(arguments);
} else {
sorters = me.getSorters();
start = me.guaranteedStart;
end = me.guaranteedEnd;
range;
if (sorters.length) {
prefetchData.sort(sorters);
range = prefetchData.getRange();
prefetchData.clear();
me.cacheRecords(range);
delete me.guaranteedStart;
delete me.guaranteedEnd;
me.guaranteeRange(start, end);
}
me.callParent(arguments);
}
} else {
me.callParent(arguments);
}
},
// overriden to provide striping of the indexes as sorting occurs.
// this cannot be done inside of sort because datachanged has already
// fired and will trigger a repaint of the bound view.
doSort: function(sorterFn) {
var me = this;
if (me.remoteSort) {
//the load function will pick up the new sorters and request the sorted data from the proxy
me.load();
} else {
me.data.sortBy(sorterFn);
if (!me.buffered) {
var range = me.getRange(),
ln = range.length,
i = 0;
for (; i < ln; i++) {
range[i].index = i;
}
}
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
* should begin with, or a RegExp to test against the field.
* @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.
* @return {Number} The matched index or -1
*/
find: function(property, value, start, anyMatch, caseSensitive, exactMatch) {
var fn = this.createFilterFn(property, value, anyMatch, caseSensitive, exactMatch);
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
* should begin with, or a RegExp to test against the field.
* @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.
* @return {Ext.data.Model} The matched record or null
*/
findRecord: function() {
var me = this,
index = me.find.apply(me, arguments);
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.
* Ignored if anyMatch is true.
*/
createFilterFn: function(property, value, anyMatch, caseSensitive, exactMatch) {
if (Ext.isEmpty(value)) {
return false;
}
value = this.data.createValueMatcher(value, anyMatch, caseSensitive, exactMatch);
return function(r) {
return value.test(r.data[property]);
};
},
/**
* 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 {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;
},
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>
* <li><b>record</b> : Ext.data.Model<p class="sub-desc">The {@link Ext.data.Model record}
* to test for filtering. Access field values using {@link Ext.data.Model#get}.</p></li>
* <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.
* @param {Number} startIndex (optional) The index to start searching at
* @return {Number} The matched index or -1
*/
findBy: function(fn, scope, start) {
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
**/
collect: function(dataIndex, allowNull, bypassFilter) {
var me = this,
data = (bypassFilter === true && me.snapshot) ? me.snapshot: me.data;
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
* the dataset size. <b>Note</b>: see the Important note in {@link #load}.</p>
* @return {Number} The number of Records in the Store's cache.
*/
getCount: function() {
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
* could be loaded into the Store if the Store contained all data
* @return {Number} The total number of Model instances available via the Proxy
*/
getTotalCount: function() {
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.
*/
getAt: function(index) {
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)
* @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.
*/
getById: function(id) {
return (this.snapshot || this.data).findBy(function(record) {
return record.getId() === id;
});
},
/**
* 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.
*/
indexOf: function(record) {
return this.data.indexOf(record);
},
/**
* 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);
},
/**
* 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);
},
/**
* Remove all items from the store.
* @param {Boolean} silent Prevent the `clear` event from being fired.
*/
removeAll: function(silent) {
var me = this;
me.clearData();
if (me.snapshot) {
me.snapshot.clear();
}
if (silent !== true) {
me.fireEvent('clear', me);
}
},
/*
* 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
* name and the first record being the value. The grouped parameter is only honored if
* the store has a groupField.
* @return {Ext.data.Model/undefined} The first model instance in the store, or undefined
*/
first: function(grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(function(records) {
return records.length ? records[0] : undefined;
}, me, true);
} else {
return me.data.first();
}
},
/**
* 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
* name and the last record being the value. The grouped parameter is only honored if
* the store has a groupField.
* @return {Ext.data.Model/undefined} The last model instance in the store, or undefined
*/
last: function(grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(function(records) {
var len = records.length;
return len ? records[len - 1] : undefined;
}, me, true);
} else {
return me.data.last();
}
},
/**
* 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
* @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 sum for that group being the value. The grouped parameter is only honored if
* the store has a groupField.
* @return {Number} The sum
*/
sum: function(field, grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(me.getSum, me, true, [field]);
} else {
return me.getSum(me.data.items, field);
}
},
// @private, see sum
getSum: function(records, field) {
var total = 0,
i = 0,
len = records.length;
for (; i < len; ++i) {
total += records[i].get(field);
}
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
* name and the count for each group being the value. The grouped parameter is only honored if
* the store has a groupField.
* @return {Number} the count
*/
count: function(grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(function(records) {
return records.length;
}, me, true);
} else {
return me.getCount();
}
},
/**
* 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.
*/
min: function(field, grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(me.getMin, me, true, [field]);
} else {
return me.getMin(me.data.items, field);
}
},
// @private, see min
getMin: function(records, field){
var i = 1,
len = records.length,
value, min;
if (len > 0) {
min = records[0].get(field);
}
for (; i < len; ++i) {
value = records[i].get(field);
if (value < min) {
min = value;
}
}
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.
*/
max: function(field, grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(me.getMax, me, true, [field]);
} else {
return me.getMax(me.data.items, field);
}
},
// @private, see max
getMax: function(records, field) {
var i = 1,
len = records.length,
value,
max;
if (len > 0) {
max = records[0].get(field);
}
for (; i < len; ++i) {
value = records[i].get(field);
if (value > max) {
max = value;
}
}
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.
*/
average: function(field, grouped) {
var me = this;
if (grouped && me.isGrouped()) {
return me.aggregate(me.getAverage, me, true, [field]);
} else {
return me.getAverage(me.data.items, field);
}
},
// @private, see average
getAverage: function(records, field) {
var i = 0,
len = records.length,
sum = 0;
if (records.length > 0) {
for (; i < len; ++i) {
sum += records[i].get(field);
}
return sum / len;
}
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.
* @param {Object} scope (optional) The scope to execute the function in. Defaults to 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
* name and the group average being the value. The grouped parameter is only honored if
* the store has a groupField.
* @param {Array} args (optional) Any arguments to append to the function call
* @return {Object} An object literal with the group names and their appropriate values.
*/
aggregate: function(fn, scope, grouped, args) {
args = args || [];
if (grouped && this.isGrouped()) {
var groups = this.getGroups(),
i = 0,
len = groups.length,
out = {},
group;
for (; i < len; ++i) {
group = groups[i];
out[group.name] = fn.apply(scope || this, [group.children].concat(args));
}
return out;
} else {
return fn.apply(scope || this, [this.data.items].concat(args));
}
}
});