Grouping is a way to group data by diffrent criteria. jqGrid support currently one level grouping.

The simple way to group in jqGrid is to enable grouping with the grid option grouping:true and define a field name on which grouping occur. The name should correspondent of the name in colModel The definituion is done with array groupField which is a part of another grid option groupingView.

It is important to note that if you want grouping to be correct, then the data should come from server to grid sorted by that field. When we are in local mode (the data is array) the data is grouped (sorted) automatically so there is no need to define additional sort column.

In order to inform the server that we want to have a grouped data, jqGrid add to the sidx parameter the groupField name on which we group. This done only if we have enabled the grouping and the data is remote.

For example if the grouping configuration is defined as:

jQuery("#grid").jqGrid({ 
  ...
  grouping:true, 
  groupingView : { 
     groupField : ['name'],
     groupDataSorted : true 
  }, 
  caption: "Grouping" 
});

then the request send to the server will look like this (using FireBug)

We should get this information from the request, perform the appropriate sorting server side and return the requested data to the grid. The grid then get the data and do the grouping adding the appropriate (defined) headers and footers.

1. When the grouping is enabled, the following options will be set explicit into the code:

• scroll = false;
• rownumbers = false;
• treeGrid = false;
• gridview = true (afterInsertRow does not fire too);

Please refer in grid options for detailed information on what these options mean

All options in grouping are set as grid options and can be changed dynamically using the setGridParam method. Two options are related to grouping

1. grouping
2. groupingView

The first option grouping is Boolean and enables or disables the grouping feature into the grid. The default values of this option is false. To enable grouping set it to true - i.e grouping : true

The groupingView option is actually a object and consist a lot of other options. Below is a example on how this should be used:

jQuery("#grid").jqGrid({ 
  ...
  groupingView : { 
     groupField : ['name'],
     groupDataSorted : true 
  }
  ...
});

Below is the list of the options that are part of groupingView option

Additionally if the group summary footer row is enabled we use a option in column model to set the type of the summary field. We add two options in colModel and it name is summaryType and summaryTpl.

This option can be a string with certain values or a user defined function. Bellow is a example of using this option:

jQuery("#grid").jqGrid({ 
  ...
  colModel : [
     {..},
     {name:'amount',index:'amount', width:80, align:"right", sorttype:'number',formatter:'number',summaryType:'sum'},
     ...
  ],
  ...
});

The option determines what type of calculation we should do with the current group value applied to column. Currently we support the following build in functions:

• sum - apply the sum function to the current group value and return the result
• count - apply the count function to the current group value and return the result
• avg - apply the average function to the current group value and return the result
• min - apply the min function to the current group value and return the result
• max - apply the max function to the current group value and return the result

The option can be defined as function. If defined we pass three parameters to it - the current value, the name and the record object. The function should return value. Note that this value will be used again for the group value until it changes.

Bellow is a example on using this function - simulating the sum function.

function mysum(val, name, record)
{
return parseFloat(val||0) + parseFloat((record[name]||0));
}
 
jQuery("#grid").jqGrid({ 
  ...
  colModel : [
     {..},
     {name:'amount',index:'amount', width:80, align:"right", sorttype:'number',formatter:'number',summaryType:mysum},
     ...
  ],
  ...
});

This option acts as template which can be used in the summary footer row. By default its value is defined as {0} - which means that this will print the summary value. The parameter can contain any valid HTML code.

Bellow are the methods that can be used with the grouping.