Upgrade to ExtJS 3.1.1 - Released 02/08/2010
[extjs.git] / docs / source / GroupingView.html
index f85429f..3915285 100644 (file)
@@ -1,5 +1,6 @@
 <html>\r
 <head>\r
 <html>\r
 <head>\r
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
   <title>The source code</title>\r
     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
   <title>The source code</title>\r
     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
@@ -140,6 +141,13 @@ var grid = new Ext.grid.GridPanel({
      * </code></pre>\r
      */\r
     groupTextTpl : '{text}',\r
      * </code></pre>\r
      */\r
     groupTextTpl : '{text}',\r
+\r
+    <div id="cfg-Ext.grid.GroupingView-groupMode"></div>/**\r
+     * @cfg {String} groupMode Indicates how to construct the group identifier. <tt>'value'</tt> constructs the id using\r
+     * raw value, <tt>'display'</tt> constructs the id using the rendered value. Defaults to <tt>'value'</tt>.\r
+     */\r
+    groupMode: 'value',\r
+\r
     <div id="cfg-Ext.grid.GroupingView-groupRenderer"></div>/**\r
      * @cfg {Function} groupRenderer This property must be configured in the {@link Ext.grid.Column} for\r
      * each column.\r
     <div id="cfg-Ext.grid.GroupingView-groupRenderer"></div>/**\r
      * @cfg {Function} groupRenderer This property must be configured in the {@link Ext.grid.Column} for\r
      * each column.\r
@@ -165,6 +173,10 @@ var grid = new Ext.grid.GridPanel({
             );\r
         }\r
         this.startGroup.compile();\r
             );\r
         }\r
         this.startGroup.compile();\r
+        if(!this.endGroup){\r
+            this.endGroup = '</div></div>';\r
+        }\r
+\r
         this.endGroup = '</div></div>';\r
     },\r
 \r
         this.endGroup = '</div></div>';\r
     },\r
 \r
@@ -180,11 +192,11 @@ var grid = new Ext.grid.GridPanel({
 \r
     // private\r
     onAdd : function(){\r
 \r
     // private\r
     onAdd : function(){\r
-        if(this.enableGrouping && !this.ignoreAdd){\r
+        if(this.canGroup() && !this.ignoreAdd){\r
             var ss = this.getScrollState();\r
             this.refresh();\r
             this.restoreScroll(ss);\r
             var ss = this.getScrollState();\r
             this.refresh();\r
             this.restoreScroll(ss);\r
-        }else if(!this.enableGrouping){\r
+        }else if(!this.canGroup()){\r
             Ext.grid.GroupingView.superclass.onAdd.apply(this, arguments);\r
         }\r
     },\r
             Ext.grid.GroupingView.superclass.onAdd.apply(this, arguments);\r
         }\r
     },\r
@@ -218,7 +230,7 @@ var grid = new Ext.grid.GridPanel({
         }\r
         if((item = items.get('showGroups'))){\r
             item.setDisabled(disabled);\r
         }\r
         if((item = items.get('showGroups'))){\r
             item.setDisabled(disabled);\r
-                   item.setChecked(!!this.getGroupField(), true);\r
+            item.setChecked(this.enableGrouping, true);\r
         }\r
     },\r
 \r
         }\r
     },\r
 \r
@@ -248,18 +260,55 @@ var grid = new Ext.grid.GridPanel({
         }\r
     },\r
 \r
         }\r
     },\r
 \r
+    processEvent: function(name, e){\r
+        var hd = e.getTarget('.x-grid-group-hd', this.mainBody);\r
+        if(hd){\r
+            // group value is at the end of the string\r
+            var field = this.getGroupField(),\r
+                prefix = this.getPrefix(field),\r
+                groupValue = hd.id.substring(prefix.length);\r
+\r
+            // remove trailing '-hd'\r
+            groupValue = groupValue.substr(0, groupValue.length - 3);\r
+            if(groupValue){\r
+                this.grid.fireEvent('group' + name, this.grid, field, groupValue, e);\r
+            }\r
+        }\r
+\r
+    },\r
+\r
     // private\r
     onGroupByClick : function(){\r
     // private\r
     onGroupByClick : function(){\r
+        this.enableGrouping = true;\r
         this.grid.store.groupBy(this.cm.getDataIndex(this.hdCtxIndex));\r
         this.grid.store.groupBy(this.cm.getDataIndex(this.hdCtxIndex));\r
+        this.grid.fireEvent('groupchange', this, this.grid.store.getGroupState());\r
         this.beforeMenuShow(); // Make sure the checkboxes get properly set when changing groups\r
         this.beforeMenuShow(); // Make sure the checkboxes get properly set when changing groups\r
+        this.refresh();\r
     },\r
 \r
     // private\r
     onShowGroupsClick : function(mi, checked){\r
     },\r
 \r
     // private\r
     onShowGroupsClick : function(mi, checked){\r
+    this.enableGrouping = checked;\r
         if(checked){\r
             this.onGroupByClick();\r
         }else{\r
             this.grid.store.clearGrouping();\r
         if(checked){\r
             this.onGroupByClick();\r
         }else{\r
             this.grid.store.clearGrouping();\r
+            this.grid.fireEvent('groupchange', this, null);\r
+        }\r
+    },\r
+\r
+    <div id="method-Ext.grid.GroupingView-toggleRowIndex"></div>/**\r
+     * Toggle the group that contains the specific row.\r
+     * @param {Number} rowIndex The row inside the group\r
+     * @param {Boolean} expanded (optional)\r
+     */\r
+    toggleRowIndex : function(rowIndex, expanded){\r
+        if(!this.canGroup()){\r
+            return;\r
+        }\r
+        var row = this.getRow(rowIndex);\r
+        if(row){\r
+            this.toggleGroup(this.findGroup(row), expanded);\r
         }\r
     },\r
 \r
         }\r
     },\r
 \r
@@ -269,14 +318,13 @@ var grid = new Ext.grid.GridPanel({
      * @param {Boolean} expanded (optional)\r
      */\r
     toggleGroup : function(group, expanded){\r
      * @param {Boolean} expanded (optional)\r
      */\r
     toggleGroup : function(group, expanded){\r
-        this.grid.stopEditing(true);\r
-        group = Ext.getDom(group);\r
-        var gel = Ext.fly(group);\r
-        expanded = expanded !== undefined ?\r
-                expanded : gel.hasClass('x-grid-group-collapsed');\r
-\r
-        this.state[gel.dom.id] = expanded;\r
-        gel[expanded ? 'removeClass' : 'addClass']('x-grid-group-collapsed');\r
+        var gel = Ext.get(group);\r
+        expanded = Ext.isDefined(expanded) ? expanded : gel.hasClass('x-grid-group-collapsed');\r
+        if(this.state[gel.id] !== expanded){\r
+            this.grid.stopEditing(true);\r
+            this.state[gel.id] = expanded;\r
+            gel[expanded ? 'removeClass' : 'addClass']('x-grid-group-collapsed');\r
+        }\r
     },\r
 \r
     <div id="method-Ext.grid.GroupingView-toggleAllGroups"></div>/**\r
     },\r
 \r
     <div id="method-Ext.grid.GroupingView-toggleAllGroups"></div>/**\r
@@ -316,7 +364,7 @@ var grid = new Ext.grid.GridPanel({
     // private\r
     getGroup : function(v, r, groupRenderer, rowIndex, colIndex, ds){\r
         var g = groupRenderer ? groupRenderer(v, {}, r, rowIndex, colIndex, ds) : String(v);\r
     // private\r
     getGroup : function(v, r, groupRenderer, rowIndex, colIndex, ds){\r
         var g = groupRenderer ? groupRenderer(v, {}, r, rowIndex, colIndex, ds) : String(v);\r
-        if(g === ''){\r
+        if(g === '' || g === '&#160;'){\r
             g = this.cm.config[colIndex].emptyGroupText || this.emptyGroupText;\r
         }\r
         return g;\r
             g = this.cm.config[colIndex].emptyGroupText || this.emptyGroupText;\r
         }\r
         return g;\r
@@ -326,9 +374,12 @@ var grid = new Ext.grid.GridPanel({
     getGroupField : function(){\r
         return this.grid.store.getGroupState();\r
     },\r
     getGroupField : function(){\r
         return this.grid.store.getGroupState();\r
     },\r
-    \r
+\r
     // private\r
     afterRender : function(){\r
     // private\r
     afterRender : function(){\r
+        if(!this.ds || !this.cm){\r
+            return;\r
+        }\r
         Ext.grid.GroupingView.superclass.afterRender.call(this);\r
         if(this.grid.deferRowRender){\r
             this.updateGroupWidths();\r
         Ext.grid.GroupingView.superclass.afterRender.call(this);\r
         if(this.grid.deferRowRender){\r
             this.updateGroupWidths();\r
@@ -341,15 +392,16 @@ var grid = new Ext.grid.GridPanel({
         var eg = !!groupField;\r
         // if they turned off grouping and the last grouped field is hidden\r
         if(this.hideGroupedColumn) {\r
         var eg = !!groupField;\r
         // if they turned off grouping and the last grouped field is hidden\r
         if(this.hideGroupedColumn) {\r
-            var colIndex = this.cm.findColumnIndex(groupField);\r
-            if(!eg && this.lastGroupField !== undefined) {\r
+            var colIndex = this.cm.findColumnIndex(groupField),\r
+                hasLastGroupField = Ext.isDefined(this.lastGroupField);\r
+            if(!eg && hasLastGroupField){\r
                 this.mainBody.update('');\r
                 this.cm.setHidden(this.cm.findColumnIndex(this.lastGroupField), false);\r
                 delete this.lastGroupField;\r
                 this.mainBody.update('');\r
                 this.cm.setHidden(this.cm.findColumnIndex(this.lastGroupField), false);\r
                 delete this.lastGroupField;\r
-            }else if (eg && this.lastGroupField === undefined) {\r
+            }else if (eg && !hasLastGroupField){\r
                 this.lastGroupField = groupField;\r
                 this.cm.setHidden(colIndex, true);\r
                 this.lastGroupField = groupField;\r
                 this.cm.setHidden(colIndex, true);\r
-            }else if (eg && this.lastGroupField !== undefined && groupField !== this.lastGroupField) {\r
+            }else if (eg && hasLastGroupField && groupField !== this.lastGroupField) {\r
                 this.mainBody.update('');\r
                 var oldIndex = this.cm.findColumnIndex(this.lastGroupField);\r
                 this.cm.setHidden(oldIndex, false);\r
                 this.mainBody.update('');\r
                 var oldIndex = this.cm.findColumnIndex(this.lastGroupField);\r
                 this.cm.setHidden(oldIndex, false);\r
@@ -366,37 +418,33 @@ var grid = new Ext.grid.GridPanel({
         if(rs.length < 1){\r
             return '';\r
         }\r
         if(rs.length < 1){\r
             return '';\r
         }\r
-        var groupField = this.getGroupField(),\r
-            colIndex = this.cm.findColumnIndex(groupField),\r
-            g;\r
-\r
-        this.enableGrouping = !!groupField;\r
 \r
 \r
-        if(!this.enableGrouping || this.isUpdating){\r
+        if(!this.canGroup() || this.isUpdating){\r
             return Ext.grid.GroupingView.superclass.doRender.apply(\r
                     this, arguments);\r
         }\r
             return Ext.grid.GroupingView.superclass.doRender.apply(\r
                     this, arguments);\r
         }\r
-        var gstyle = 'width:'+this.getTotalWidth()+';';\r
 \r
 \r
-        var gidPrefix = this.grid.getGridEl().id;\r
-        var cfg = this.cm.config[colIndex];\r
-        var groupRenderer = cfg.groupRenderer || cfg.renderer;\r
-        var prefix = this.showGroupName ?\r
-                     (cfg.groupName || cfg.header)+': ' : '';\r
+        var groupField = this.getGroupField(),\r
+            colIndex = this.cm.findColumnIndex(groupField),\r
+            g,\r
+            gstyle = 'width:' + this.getTotalWidth() + ';',\r
+            cfg = this.cm.config[colIndex],\r
+            groupRenderer = cfg.groupRenderer || cfg.renderer,\r
+            prefix = this.showGroupName ? (cfg.groupName || cfg.header)+': ' : '',\r
+            groups = [],\r
+            curGroup, i, len, gid;\r
 \r
 \r
-        var groups = [], curGroup, i, len, gid;\r
         for(i = 0, len = rs.length; i < len; i++){\r
             var rowIndex = startRow + i,\r
                 r = rs[i],\r
                 gvalue = r.data[groupField];\r
         for(i = 0, len = rs.length; i < len; i++){\r
             var rowIndex = startRow + i,\r
                 r = rs[i],\r
                 gvalue = r.data[groupField];\r
-                \r
+\r
                 g = this.getGroup(gvalue, r, groupRenderer, rowIndex, colIndex, ds);\r
             if(!curGroup || curGroup.group != g){\r
                 g = this.getGroup(gvalue, r, groupRenderer, rowIndex, colIndex, ds);\r
             if(!curGroup || curGroup.group != g){\r
-                gid = gidPrefix + '-gp-' + groupField + '-' + Ext.util.Format.htmlEncode(g);\r
-                       // if state is defined use it, however state is in terms of expanded\r
-                               // so negate it, otherwise use the default.\r
-                               var isCollapsed  = typeof this.state[gid] !== 'undefined' ? !this.state[gid] : this.startCollapsed;\r
-                               var gcls = isCollapsed ? 'x-grid-group-collapsed' : ''; \r
+                gid = this.constructId(gvalue, groupField, colIndex);\r
+                // if state is defined use it, however state is in terms of expanded\r
+                // so negate it, otherwise use the default.\r
+                this.state[gid] = !(Ext.isDefined(this.state[gid]) ? !this.state[gid] : this.startCollapsed);\r
                 curGroup = {\r
                     group: g,\r
                     gvalue: gvalue,\r
                 curGroup = {\r
                     group: g,\r
                     gvalue: gvalue,\r
@@ -404,7 +452,7 @@ var grid = new Ext.grid.GridPanel({
                     groupId: gid,\r
                     startRow: rowIndex,\r
                     rs: [r],\r
                     groupId: gid,\r
                     startRow: rowIndex,\r
                     rs: [r],\r
-                    cls: gcls,\r
+                    cls: this.state[gid] ? '' : 'x-grid-group-collapsed',\r
                     style: gstyle\r
                 };\r
                 groups.push(curGroup);\r
                     style: gstyle\r
                 };\r
                 groups.push(curGroup);\r
@@ -432,13 +480,27 @@ var grid = new Ext.grid.GridPanel({
      * @return {String} The group id\r
      */\r
     getGroupId : function(value){\r
      * @return {String} The group id\r
      */\r
     getGroupId : function(value){\r
-        var gidPrefix = this.grid.getGridEl().id;\r
-        var groupField = this.getGroupField();\r
-        var colIndex = this.cm.findColumnIndex(groupField);\r
-        var cfg = this.cm.config[colIndex];\r
-        var groupRenderer = cfg.groupRenderer || cfg.renderer;\r
-        var gtext = this.getGroup(value, {data:{}}, groupRenderer, 0, colIndex, this.ds);\r
-        return gidPrefix + '-gp-' + groupField + '-' + Ext.util.Format.htmlEncode(value);\r
+        var field = this.getGroupField();\r
+        return this.constructId(value, field, this.cm.findColumnIndex(field));\r
+    },\r
+\r
+    // private\r
+    constructId : function(value, field, idx){\r
+        var cfg = this.cm.config[idx],\r
+            groupRenderer = cfg.groupRenderer || cfg.renderer,\r
+            val = (this.groupMode == 'value') ? value : this.getGroup(value, {data:{}}, groupRenderer, 0, idx, this.ds);\r
+\r
+        return this.getPrefix(field) + Ext.util.Format.htmlEncode(val);\r
+    },\r
+\r
+    // private\r
+    canGroup  : function(){\r
+        return this.enableGrouping && !!this.getGroupField();\r
+    },\r
+\r
+    // private\r
+    getPrefix: function(field){\r
+        return this.grid.getGridEl().id + '-gp-' + field + '-';\r
     },\r
 \r
     // private\r
     },\r
 \r
     // private\r
@@ -453,7 +515,7 @@ var grid = new Ext.grid.GridPanel({
 \r
     // private\r
     getRows : function(){\r
 \r
     // private\r
     getRows : function(){\r
-        if(!this.enableGrouping){\r
+        if(!this.canGroup()){\r
             return Ext.grid.GroupingView.superclass.getRows.call(this);\r
         }\r
         var r = [];\r
             return Ext.grid.GroupingView.superclass.getRows.call(this);\r
         }\r
         var r = [];\r
@@ -469,10 +531,10 @@ var grid = new Ext.grid.GridPanel({
 \r
     // private\r
     updateGroupWidths : function(){\r
 \r
     // private\r
     updateGroupWidths : function(){\r
-        if(!this.enableGrouping || !this.hasRows()){\r
+        if(!this.canGroup() || !this.hasRows()){\r
             return;\r
         }\r
             return;\r
         }\r
-        var tw = Math.max(this.cm.getTotalWidth(), this.el.dom.offsetWidth-this.scrollOffset) +'px';\r
+        var tw = Math.max(this.cm.getTotalWidth(), this.el.dom.offsetWidth-this.getScrollOffset()) +'px';\r
         var gs = this.getGroups();\r
         for(var i = 0, len = gs.length; i < len; i++){\r
             gs[i].firstChild.style.width = tw;\r
         var gs = this.getGroups();\r
         for(var i = 0, len = gs.length; i < len; i++){\r
             gs[i].firstChild.style.width = tw;\r
@@ -504,14 +566,7 @@ var grid = new Ext.grid.GridPanel({
 \r
     // private\r
     onBeforeRowSelect : function(sm, rowIndex){\r
 \r
     // private\r
     onBeforeRowSelect : function(sm, rowIndex){\r
-        if(!this.enableGrouping){\r
-            return;\r
-        }\r
-        var row = this.getRow(rowIndex);\r
-        if(row && !row.offsetParent){\r
-            var g = this.findGroup(row);\r
-            this.toggleGroup(g, true);\r
-        }\r
+        this.toggleRowIndex(rowIndex, true);\r
     }\r
 });\r
 // private\r
     }\r
 });\r
 // private\r