/*!
 * Ext JS Library 3.2.0
 * Copyright(c) 2006-2010 Ext JS, Inc.
 * licensing@extjs.com
 * http://www.extjs.com/license
 */
/** * @class Ext.data.GroupingStore * @extends Ext.data.Store * A specialized store implementation that provides for grouping records by one of the available fields. This * is usually used in conjunction with an {@link Ext.grid.GroupingView} to provide the data model for * a grouped GridPanel. * * Internally, GroupingStore is simply a normal Store with multi sorting enabled from the start. The grouping field * and direction are always injected as the first sorter pair. GroupingView picks up on the configured groupField and * builds grid rows appropriately. * * @constructor * Creates a new GroupingStore. * @param {Object} config A config object containing the objects needed for the Store to access data, * and read the data into Records. * @xtype groupingstore */ Ext.data.GroupingStore = Ext.extend(Ext.data.Store, { //inherit docs constructor: function(config) { config = config || {}; //We do some preprocessing here to massage the grouping + sorting options into a single //multi sort array. If grouping and sorting options are both presented to the constructor, //the sorters array consists of the grouping sorter object followed by the sorting sorter object //see Ext.data.Store's sorting functions for details about how multi sorting works this.hasMultiSort = true; this.multiSortInfo = this.multiSortInfo || {sorters: []}; var sorters = this.multiSortInfo.sorters, groupField = config.groupField || this.groupField, sortInfo = config.sortInfo || this.sortInfo, groupDir = config.groupDir || this.groupDir; //add the grouping sorter object first if(groupField){ sorters.push({ field : groupField, direction: groupDir }); } //add the sorting sorter object if it is present if (sortInfo) { sorters.push(sortInfo); } Ext.data.GroupingStore.superclass.constructor.call(this, config); this.addEvents(
/** * @event groupchange * Fired whenever a call to store.groupBy successfully changes the grouping on the store * @param {Ext.data.GroupingStore} store The grouping store * @param {String} groupField The field that the store is now grouped by */ 'groupchange' ); this.applyGroupField(); },
/** * @cfg {String} groupField * The field name by which to sort the store's data (defaults to ''). */
/** * @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 field name as the 'groupBy' param with each XHR call. */ remoteGroup : false,
/** * @cfg {Boolean} groupOnSort * True to sort the data on the grouping field when a grouping operation occurs, false to sort based on the * existing sort info (defaults to false). */ groupOnSort:false, groupDir : 'ASC',
/** * Clears any existing grouping and refreshes the data using the default sort. */ clearGrouping : function(){ this.groupField = false; if(this.remoteGroup){ if(this.baseParams){ delete this.baseParams.groupBy; delete this.baseParams.groupDir; } var lo = this.lastOptions; if(lo && lo.params){ delete lo.params.groupBy; delete lo.params.groupDir; } this.reload(); }else{ this.sort(); this.fireEvent('datachanged', this); } },
/** * Groups the data by the specified field. * @param {String} field The field name by which to sort the store's data * @param {Boolean} forceRegroup (optional) True to force the group to be refreshed even if the field passed * in is the same as the current grouping field, false to skip grouping on the same field (defaults to false) */ groupBy : function(field, forceRegroup, direction) { direction = direction ? (String(direction).toUpperCase() == 'DESC' ? 'DESC' : 'ASC') : this.groupDir; if (this.groupField == field && this.groupDir == direction && !forceRegroup) { return; // already grouped by this field } //check the contents of the first sorter. If the field matches the CURRENT groupField (before it is set to the new one), //remove the sorter as it is actually the grouper. The new grouper is added back in by this.sort sorters = this.multiSortInfo.sorters; if (sorters.length > 0 && sorters[0].field == this.groupField) { sorters.shift(); } this.groupField = field; this.groupDir = direction; this.applyGroupField(); var fireGroupEvent = function() { this.fireEvent('groupchange', this, this.getGroupState()); }; if (this.groupOnSort) { this.sort(field, direction); fireGroupEvent.call(this); return; } if (this.remoteGroup) { this.on('load', fireGroupEvent, this, {single: true}); this.reload(); } else { this.sort(sorters); fireGroupEvent.call(this); } }, //GroupingStore always uses multisorting so we intercept calls to sort here to make sure that our grouping sorter object //is always injected first. sort : function(fieldName, dir) { if (this.remoteSort) { return Ext.data.GroupingStore.superclass.sort.call(this, fieldName, dir); } var sorters = []; //cater for any existing valid arguments to this.sort, massage them into an array of sorter objects if (Ext.isArray(arguments[0])) { sorters = arguments[0]; } else if (fieldName == undefined) { //we preserve the existing sortInfo here because this.sort is called after //clearGrouping and there may be existing sorting sorters = [this.sortInfo]; } else { //TODO: this is lifted straight from Ext.data.Store's singleSort function. It should instead be //refactored into a common method if possible var field = this.fields.get(fieldName); if (!field) return false; var name = field.name, sortInfo = this.sortInfo || null, sortToggle = this.sortToggle ? this.sortToggle[name] : null; if (!dir) { if (sortInfo && sortInfo.field == name) { // toggle sort dir dir = (this.sortToggle[name] || 'ASC').toggle('ASC', 'DESC'); } else { dir = field.sortDir; } } this.sortToggle[name] = dir; this.sortInfo = {field: name, direction: dir}; sorters = [this.sortInfo]; } //add the grouping sorter object as the first multisort sorter if (this.groupField) { sorters.unshift({direction: this.groupDir, field: this.groupField}); } return this.multiSort.call(this, sorters, dir); }, /** * @private * Saves the current grouping field and direction to this.baseParams and this.lastOptions.params * if we're using remote grouping. Does not actually perform any grouping - just stores values */ applyGroupField: function(){ if (this.remoteGroup) { if(!this.baseParams){ this.baseParams = {}; } Ext.apply(this.baseParams, { groupBy : this.groupField, groupDir: this.groupDir }); var lo = this.lastOptions; if (lo && lo.params) { lo.params.groupDir = this.groupDir; //this is deleted because of a bug reported at http://www.extjs.com/forum/showthread.php?t=82907 delete lo.params.groupBy; } } }, /** * @private * TODO: This function is apparently never invoked anywhere in the framework. It has no documentation * and should be considered for deletion */ applyGrouping : function(alwaysFireChange){ if(this.groupField !== false){ this.groupBy(this.groupField, true, this.groupDir); return true; }else{ if(alwaysFireChange === true){ this.fireEvent('datachanged', this); } return false; } }, /** * @private * Returns the grouping field that should be used. If groupOnSort is used this will be sortInfo's field, * otherwise it will be this.groupField * @return {String} The group field */ getGroupState : function(){ return this.groupOnSort && this.groupField !== false ? (this.sortInfo ? this.sortInfo.field : undefined) : this.groupField; } }); Ext.reg('groupingstore', Ext.data.GroupingStore);