source/data/GroupingStore.js

   1 /*\r
   2  * Ext JS Library 2.2.1\r
   3  * Copyright(c) 2006-2009, Ext JS, LLC.\r
   4  * licensing@extjs.com\r
   5  * \r
   6  * http://extjs.com/license\r
   7  */\r
   8 \r
   9 /**\r
  10  * @class Ext.data.GroupingStore\r
  11  * @extends Ext.data.Store\r
  12  * A specialized store implementation that provides for grouping records by one of the available fields. This\r
  13  * is usually used in conjunction with an {@link Ext.grid.GroupingView} to proved the data model for\r
  14  * a grouped GridPanel.\r
  15  * @constructor\r
  16  * Creates a new GroupingStore.\r
  17  * @param {Object} config A config object containing the objects needed for the Store to access data,\r
  18  * and read the data into Records.\r
  19  */\r
  20 Ext.data.GroupingStore = Ext.extend(Ext.data.Store, {\r
  21     /**\r
  22      * @cfg {String} groupField\r
  23      * The field name by which to sort the store's data (defaults to '').\r
  24      */\r
  25     /**\r
  26      * @cfg {Boolean} remoteGroup\r
  27      * True if the grouping should apply on the server side, false if it is local only (defaults to false).  If the\r
  28      * grouping is local, it can be applied immediately to the data.  If it is remote, then it will simply act as a\r
  29      * helper, automatically sending the grouping field name as the 'groupBy' param with each XHR call.\r
  30      */\r
  31     remoteGroup : false,\r
  32     /**\r
  33      * @cfg {Boolean} groupOnSort\r
  34      * True to sort the data on the grouping field when a grouping operation occurs, false to sort based on the\r
  35      * existing sort info (defaults to false).\r
  36      */\r
  37     groupOnSort:false,\r
  38 \r
  39     /**\r
  40      * Clears any existing grouping and refreshes the data using the default sort.\r
  41      */\r
  42     clearGrouping : function(){\r
  43         this.groupField = false;\r
  44         if(this.remoteGroup){\r
  45             if(this.baseParams){\r
  46                 delete this.baseParams.groupBy;\r
  47             }\r
  48             this.reload();\r
  49         }else{\r
  50             this.applySort();\r
  51             this.fireEvent('datachanged', this);\r
  52         }\r
  53     },\r
  54 \r
  55     /**\r
  56      * Groups the data by the specified field.\r
  57      * @param {String} field The field name by which to sort the store's data\r
  58      * @param {Boolean} forceRegroup (optional) True to force the group to be refreshed even if the field passed\r
  59      * in is the same as the current grouping field, false to skip grouping on the same field (defaults to false)\r
  60      */\r
  61     groupBy : function(field, forceRegroup){\r
  62         if(this.groupField == field && !forceRegroup){\r
  63             return; // already grouped by this field\r
  64         }\r
  65         this.groupField = field;\r
  66         if(this.remoteGroup){\r
  67             if(!this.baseParams){\r
  68                 this.baseParams = {};\r
  69             }\r
  70             this.baseParams['groupBy'] = field;\r
  71         }\r
  72         if(this.groupOnSort){\r
  73             this.sort(field);\r
  74             return;\r
  75         }\r
  76         if(this.remoteGroup){\r
  77             this.reload();\r
  78         }else{\r
  79             var si = this.sortInfo || {};\r
  80             if(si.field != field){\r
  81                 this.applySort();\r
  82             }else{\r
  83                 this.sortData(field);\r
  84             }\r
  85             this.fireEvent('datachanged', this);\r
  86         }\r
  87     },\r
  88 \r
  89     // private\r
  90     applySort : function(){\r
  91         Ext.data.GroupingStore.superclass.applySort.call(this);\r
  92         if(!this.groupOnSort && !this.remoteGroup){\r
  93             var gs = this.getGroupState();\r
  94             if(gs && gs != this.sortInfo.field){\r
  95                 this.sortData(this.groupField);\r
  96             }\r
  97         }\r
  98     },\r
  99 \r
 100     // private\r
 101     applyGrouping : function(alwaysFireChange){\r
 102         if(this.groupField !== false){\r
 103             this.groupBy(this.groupField, true);\r
 104             return true;\r
 105         }else{\r
 106             if(alwaysFireChange === true){\r
 107                 this.fireEvent('datachanged', this);\r
 108             }\r
 109             return false;\r
 110         }\r
 111     },\r
 112 \r
 113     // private\r
 114     getGroupState : function(){\r
 115         return this.groupOnSort && this.groupField !== false ?\r
 116                (this.sortInfo ? this.sortInfo.field : undefined) : this.groupField;\r
 117     }\r
 118 });