Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / GroupingSummary.html
1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-grid.feature.GroupingSummary'>/**
2 </span> * @class Ext.grid.feature.GroupingSummary
3  * @extends Ext.grid.feature.Grouping
4  * 
5  * This feature adds an aggregate summary row at the bottom of each group that is provided
6  * by the {@link Ext.grid.feature.Grouping} feature. There are 2 aspects to the summary:
7  * 
8  * ## Calculation
9  * 
10  * The summary value needs to be calculated for each column in the grid. This is controlled
11  * by the summaryType option specified on the column. There are several built in summary types,
12  * which can be specified as a string on the column configuration. These call underlying methods
13  * on the store:
14  *
15  *  - {@link Ext.data.Store#count count}
16  *  - {@link Ext.data.Store#sum sum}
17  *  - {@link Ext.data.Store#min min}
18  *  - {@link Ext.data.Store#max max}
19  *  - {@link Ext.data.Store#average average}
20  *
21  * Alternatively, the summaryType can be a function definition. If this is the case,
22  * the function is called with an array of records to calculate the summary value.
23  * 
24  * ## Rendering
25  * 
26  * Similar to a column, the summary also supports a summaryRenderer function. This
27  * summaryRenderer is called before displaying a value. The function is optional, if
28  * not specified the default calculated value is shown. The summaryRenderer is called with:
29  *
30  *  - value {Object} - The calculated value.
31  *  - data {Object} - Contains all raw summary values for the row.
32  *  - field {String} - The name of the field we are calculating
33  * 
34  * ## Example Usage
35  *
36  *     Ext.define('TestResult', {
37  *         extend: 'Ext.data.Model',
38  *         fields: ['student', 'subject', {
39  *             name: 'mark',
40  *             type: 'int'
41  *         }]
42  *     });
43  *     
44  *     Ext.create('Ext.grid.Panel', {
45  *         width: 200,
46  *         height: 240,
47  *         renderTo: document.body,
48  *         features: [{
49  *             groupHeaderTpl: 'Subject: {name}',
50  *             ftype: 'groupingsummary'
51  *         }],
52  *         store: {
53  *             model: 'TestResult',
54  *             groupField: 'subject',
55  *             data: [{
56  *                 student: 'Student 1',
57  *                 subject: 'Math',
58  *                 mark: 84
59  *             },{
60  *                 student: 'Student 1',
61  *                 subject: 'Science',
62  *                 mark: 72
63  *             },{
64  *                 student: 'Student 2',
65  *                 subject: 'Math',
66  *                 mark: 96
67  *             },{
68  *                 student: 'Student 2',
69  *                 subject: 'Science',
70  *                 mark: 68
71  *             }]
72  *         },
73  *         columns: [{
74  *             dataIndex: 'student',
75  *             text: 'Name',
76  *             summaryType: 'count',
77  *             summaryRenderer: function(value){
78  *                 return Ext.String.format('{0} student{1}', value, value !== 1 ? 's' : ''); 
79  *             }
80  *         }, {
81  *             dataIndex: 'mark',
82  *             text: 'Mark',
83  *             summaryType: 'average'
84  *         }]
85  *     });
86  */
87 Ext.define('Ext.grid.feature.GroupingSummary', {
88     
89     /* Begin Definitions */
90     
91     extend: 'Ext.grid.feature.Grouping',
92     
93     alias: 'feature.groupingsummary',
94     
95     mixins: {
96         summary: 'Ext.grid.feature.AbstractSummary'
97     },
98     
99     /* End Definitions */
100
101      
102 <span id='Ext-grid.feature.GroupingSummary-method-getFeatureTpl'>   /**
103 </span>    * Modifies the row template to include the summary row.
104     * @private
105     * @return {String} The modified template
106     */
107    getFeatureTpl: function() {
108         var tpl = this.callParent(arguments);
109             
110         if (this.showSummaryRow) {
111             // lop off the end &lt;/tpl&gt; so we can attach it
112             tpl = tpl.replace('&lt;/tpl&gt;', '');
113             tpl += '{[this.printSummaryRow(xindex)]}&lt;/tpl&gt;';
114         }
115         return tpl;
116     },
117     
118 <span id='Ext-grid.feature.GroupingSummary-method-getFragmentTpl'>    /**
119 </span>     * Gets any fragments needed for the template.
120      * @private
121      * @return {Object} The fragments
122      */
123     getFragmentTpl: function() {
124         var me = this,
125             fragments = me.callParent();
126             
127         Ext.apply(fragments, me.getSummaryFragments());
128         if (me.showSummaryRow) {
129             // this gets called before render, so we'll setup the data here.
130             me.summaryGroups = me.view.store.getGroups();
131             me.summaryData = me.generateSummaryData();
132         }
133         return fragments;
134     },
135     
136 <span id='Ext-grid.feature.GroupingSummary-method-getPrintData'>    /**
137 </span>     * Gets the data for printing a template row
138      * @private
139      * @param {Number} index The index in the template
140      * @return {Array} The template values
141      */
142     getPrintData: function(index){
143         var me = this,
144             columns = me.view.headerCt.getColumnsForTpl(),
145             i = 0,
146             length = columns.length,
147             data = [],
148             name = me.summaryGroups[index - 1].name,
149             active = me.summaryData[name],
150             column;
151             
152         for (; i &lt; length; ++i) {
153             column = columns[i];
154             column.gridSummaryValue = this.getColumnValue(column, active);
155             data.push(column);
156         }
157         return data;
158     },
159     
160 <span id='Ext-grid.feature.GroupingSummary-method-generateSummaryData'>    /**
161 </span>     * Generates all of the summary data to be used when processing the template
162      * @private
163      * @return {Object} The summary data
164      */
165     generateSummaryData: function(){
166         var me = this,
167             data = {},
168             remoteData = {},
169             store = me.view.store,
170             groupField = this.getGroupField(),
171             reader = store.proxy.reader,
172             groups = me.summaryGroups,
173             columns = me.view.headerCt.getColumnsForTpl(),
174             i,
175             length,
176             fieldData,
177             root,
178             key,
179             comp;
180             
181         for (i = 0, length = groups.length; i &lt; length; ++i) {
182             data[groups[i].name] = {};
183         }
184         
185 <span id='Ext-grid.feature.GroupingSummary-cfg-remoteRoot'>    /**
186 </span>     * @cfg {String} remoteRoot.  The name of the property
187      * which contains the Array of summary objects.  Defaults to &lt;tt&gt;undefined&lt;/tt&gt;.
188      * It allows to use server-side calculated summaries.
189      */
190         if (me.remoteRoot &amp;&amp; reader.rawData) {
191             // reset reader root and rebuild extractors to extract summaries data
192             root = reader.root;
193             reader.root = me.remoteRoot;
194             reader.buildExtractors(true);
195             Ext.Array.each(reader.getRoot(reader.rawData), function(value) {
196                  data[value[groupField]] = value;
197                  data[value[groupField]]._remote = true;
198             });
199             // restore initial reader configuration
200             reader.root = root;
201             reader.buildExtractors(true);
202         }
203         
204         for (i = 0, length = columns.length; i &lt; length; ++i) {
205             comp = Ext.getCmp(columns[i].id);
206             fieldData = me.getSummary(store, comp.summaryType, comp.dataIndex, true);
207             
208             for (key in fieldData) {
209                 if (fieldData.hasOwnProperty(key)) {
210                     if (!data[key]._remote) {
211                         data[key][comp.dataIndex] = fieldData[key];
212                     }
213                 }
214             }
215         }
216         return data;
217     }
218 });
219 </pre></pre></body></html>