December 29, 2009

How To use GroupHeaderGrid Ext JS plugin

GroupHeaderGrid is a custom plugin that implements support for grouping columns in a grid. When you are serious about using ExtJS on your application, I am sure many of you will come across this requirement where you need to group the column headers in display of records. The plugin do not have specific site but was born out collaboration in the Ext Js forum. It all started with this thread. We will have look at how to use the plugin and some simple examples.

Getting the Plugin
You can find few versions listed and available for download in this thread. I will use the plugin the latest version (1.4) which is for Ext JS 3.0. The plugin comes with a CSS and javascript file. The zip file also contains an example.

Installing and Using The Plugin
Installing the plugin is simply copying the script file and CSS file in appropriate directory. These need not be added into the Ext JS folder ( I usually keep the distribution un-touched) and keep separate folders for my extensions and generic components. For example, lets consider a yearly report for a group of companies. The monthly turnover for each subsidy is displayed in the grid. Now, we need to separate data for each quarter.

To use the plugin with the grid you need to create an instance of the plugin and add it to the grid. Here is code snippet for our example:
...
plugins: [new Ext.ux.plugins.GroupHeaderGrid({
rows:[ [                    
{},
{header: 'Q1', colspan: 3, align: 'center'},
{header: 'Q2', colspan: 3, align: 'center'},
{header: 'Q3', colspan: 3, align: 'center'},
{header: 'Q4', colspan: 3, align: 'center'}                    
]]
})]
...
The rows attribute is most important field for the GroupHeaderGrid class. We specify all the header information as rows. In our example, we have only one level of grouped header. The first column ie, Subsidiary is not grouped. The other 12 columns are grouped into quarters. For each grouping we provide the header's label and column span. In the above example, I have provided the header label, column span and text alignment.

If you have another layer of grouped headers, you will have to add an array into the rows attribute. As per the Ext JS forums, the plugin supports unlimited number of headers. I have used only 2 levels so far. Here is the complete example code:
Ext.onReady(function() {
new Ext.Viewport({
layout: 'border',
items: [{
region: 'center',
xtype: 'grid',
title: 'Yearly Report',
store: new Ext.data.SimpleStore({
fields: ['Subsidiary','Jan', 'Feb', 'Mar', 'Apr', 'May',
'Jun', 'Jul', 'Aug', 'Spt', 'Oct', 'Nov','Dec'],
data: [
['OGC', 2300, 4200, 105600, 5000, 15000, 
7000, 8000, 9100, 10000, 11000, 4000, 5000],
['OGH Ltd', 2100, 6700, 209000, 5000, 500,
7800, 8000, 9600, 10600, 11000, 67000,234000],
['T-DEL', 2320, 7100, 240000, 5800, 7500,
7000, 8500, 9200, 10000, 13400, 3300,24000],
['OGC-I&E', 22000, 2300, 1500, 5000, 8300,
7500, 8000, 99900, 10000, 17300, 21000,76000]
]}),
colModel: new Ext.grid.ColumnModel({
columns: [
{header: 'Subsidiary', dataIndex: 'Subsidiary'},
{header: 'Jan', dataIndex: 'Jan'},
{header: 'Feb', dataIndex: 'Feb'},
{header: 'Mar', dataIndex: 'Mar'},
{header: 'Apr', dataIndex: 'Apr'},
{header: 'May', dataIndex: 'May'},
{header: 'Jun', dataIndex: 'Jun'},
{header: 'Jul', dataIndex: 'Jul'},
{header: 'Aug', dataIndex: 'Aug'},
{header: 'Spt', dataIndex: 'Spt'},
{header: 'Oct', dataIndex: 'Oct'},
{header: 'Nov', dataIndex: 'Nov'},
{header: 'Dec', dataIndex: 'Dec'}
],
defaultSortable: true
}),
plugins: [new Ext.ux.plugins.GroupHeaderGrid({
rows: [[                    
{},
{header: 'Q1', colspan: 3, align: 'center'},
{header: 'Q2', colspan: 3, align: 'center'},
{header: 'Q3', colspan: 3, align: 'center'},
{header: 'Q4', colspan: 3, align: 'center'}                    
]]
})]
}]
});
});
And that's it for now.

Read other ExtJS related articles!

No comments :