Create the best Web experiences in browsers and devices with our user interface controls designed expressly for jQuery, ASP.NET MVC, HTML 5 and CSS 3. You’ll be building on a solid and proven foundation without any plug-ins or extensions, just real world best practices and the most forward-thinking, robust Web technology.
Infragistics NetAdvantage jQuery API Reference
ui.igGridGroupBy
Both the igGrid and igHierarchicalGrid controls feature column grouping in the grid. The grouping feature allows users to group rows of data in the grid by common column values. Further information regarding the classes, options, events, methods and themes of this API are available under the associated tabs above.
The following code snippet demonstrates how to initialize the igGrid control.
Click here for more information on how to get started using this API. For details on how to reference the required scripts and themes for the igGrid control read, Using JavaScript Resouces in NetAdvantage for jQuery and Styling and Theming NetAdvantage for jQuery.Code Sample
<!doctype html>
<html>
<head>
<title>Infragistics NetAdvantage for jQuery igGridGroupBy</title>
<!-- Infragistics Combined CSS -->
<link href="themes/ig/jquery.ui.custom.css" rel="stylesheet" type="text/css" />
<link href="themes/base/ig.ui.css" rel="stylesheet" type="text/css" />
<!-- jQuery Core -->
<script src="js/jquery.js" type="text/javascript"></script>
<!-- jQuery UI -->
<script src="js/jquery-ui.js" type="text/javascript"></script>
<!-- jQuery Templates: http://api.jquery.com/category/plugins/templates/ -->
<script src="js/jquery.tmpl.js" type="text/javascript"></script>
<!-- Infragistics Combined Scripts -->
<script src="js/ig.ui.js" type="text/javascript"></script>
<script type="text/javascript">
$(function () {
var products = [
{ "ProductID": 1, "ProductGroup": "9001", "Name": "Adjustable Race", "ProductNumber": "AR-5381" },
{ "ProductID": 2, "ProductGroup": "9001", "Name": "Bearing Ball", "ProductNumber": "BA-8327" },
{ "ProductID": 3, "ProductGroup": "8010", "Name": "BB Ball Bearing", "ProductNumber": "BE-2349" },
{ "ProductID": 4, "ProductGroup": "9001", "Name": "Headset Ball Bearings", "ProductNumber": "BE-2908" },
{ "ProductID": 316, "ProductGroup": "8010", "Name": "Blade", "ProductNumber": "BL-2036" },
{ "ProductID": 317, "ProductGroup": "9001", "Name": "LL Crankarm", "ProductNumber": "CA-5965" },
{ "ProductID": 318, "ProductGroup": "8010", "Name": "ML Crankarm", "ProductNumber": "CA-6738" },
{ "ProductID": 319, "ProductGroup": "8010", "Name": "HL Crankarm", "ProductNumber": "CA-7457" },
{ "ProductID": 320, "ProductGroup": "9001", "Name": "Chainring Bolts", "ProductNumber": "CB-2903" }
];
$("#grid").igGrid({
autoGenerateColumns: true,
dataSource: products,
height: "400px",
features: [{
name: "GroupBy",
type: "local",
columnSettings: [{
columnKey: "ProductGroup",
isGroupBy: true
}, {
columnKey: "ProductID",
allowGrouping: false
}]
}]
});
$("#grid").igGrid("dataBind");
});
</script>
</head>
<body>
<table id="grid">
</table>
</body>
</html>
Related Samples
Related Topics
Dependencies
-
collapseTooltip
- Type:
- string
- Default:
- ""
Specifies the collapse indicator tooltip for grouped rows.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", collapseTooltip: "Collapse group" } ] }); //Get var opValue = $(".selector").igGridGroupBy("option", "collapseTooltip"); //Set $(".selector").igGridGroupBy("option", "collapseTooltip", "Collapse group"); -
columnSettings
- Type:
- object
- Default:
- []
GroupBy column settings.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", columnSettings: [ { columnKey: "Name", isGroupBy: true }, { columnKey: "BoxArt", allowGrouping: false } ] } ] }); //Get var arrayOfColumnSettings = $(".selector").igGridGroupBy("option", "columnSettings"); //Set $(".selector").igGridGroupBy("option", "columnSettings", arrayOfColumnSettings);-
allowGrouping
- Type:
- bool
- Default:
- true
Enables/disables a column to participate in grouping. By default all columns can be grouped.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", columnSettings: [ { columnKey: "Name", allowGrouping: false } ] } ] }); //Get var groupBySettings = $(".selector").igGridGroupBy("option", "columnSettings"); var allowGroupingFirstColumn = groupBySettings[0].allowGrouping; //Set //get the array of column settings var groupBySettings = $(".selector").igGridGroupBy("option", "columnSettings"); //set new value for the first column groupBySettings[0].allowGrouping = false; $(".selector").igGridGroupBy("option", "columnSettings", groupBySettings); -
groupComparerFunction
- Type:
- function
- Default:
- null
Specifies a custom group by function, which accepts the column setting, the first and the second value to compare and returns bool.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", columnSettings: [{ columnKey: "Name", groupComparerFunction: function (columnSetting, val1, val2) { return (val1 === val2); } }] } ] }); -
isGroupBy
- Type:
- bool
- Default:
- false
Specifies if a column should be grouped by default.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", columnSettings: [ { columnKey: "Name", isGroupBy: true } ] } ] }); -
summaries
- Type:
- object
- Default:
- []
A list of summaries to render for the column.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", columnSettings: [ // The code in this example specifies that data must be grouped by // the Color column and the average, the minimum and the maximum of // the ListPrice column must be calculated and displayed for each group. { columnKey: "Color", isGroupBy: true }, { columnKey: "ListPrice", allowGrouping: false, summaries: [ { summaryFunction: "avg", text: " average:" }, { summaryFunction: "min", text: " minimal:" }, { summaryFunction: "max", text: " maximal:" } ] } ] } ] });-
customSummary
- Type:
- object
- Default:
- null
Specifies a custom summary function, which is called for each group, accepts an array of cell values for the specific column and returns the custom summary result.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", columnSettings: [ { columnKey: "Color", isGroupBy: true }, { columnKey: "ListPrice", allowGrouping: false, summaries: [ { // Set average price summary value summaryFunction: "avg", text: " average:" }, { // Set a custom function to calculate the difference between // the minimum and the maximum values in the group summaryFunction: "custom", text: " delta:", customSummary: function(valuesList) { // Initialize minmum and maximum values with the first element var min = valuesList[1], max = valuesList[1]; // Iterate all values in the list and find minimum and maximum for(i = 1; i < valuesList.length; i++) { if(valuesList[i] < min) min = valuesList[i]; if(valuesList[i] > max) max = valuesList[i]; } // Return difference between minimum and maximum return (max - min); } } ] } ] } ] }); -
summaryFunction
- Type:
- enumeration
- Default:
- avg
the summary function .
Members
- avg
- Type:string
- average.
- min
- Type:string
- minimal.
- max
- Type:string
- maximal.
- sum
- Type:string
- sum.
- count
- Type:string
- count.
- custom
- Type:string
- custom summary.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", columnSettings: [{ columnKey: "Name", summaries: [{ summaryFunction: "Avg" }] }] }] }); -
text
- Type:
- object
- Default:
- null
Specifies the Summary text that will be shown before the value.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", columnSettings: [{ columnKey: "Name", summaries: [{ summaryFunction: "Avg", text: "Average:" }] }] }] });
-
emptyGroupByAreaContent
- Type:
- string
- Default:
- ""
Text that will be shown in the GroupBy area when there are no grouped columns.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", columnSettings: [{ columnKey: "Name", emptyGroupByAreaContent: "Put here columns to group by" }] }] }); // Get var opValue = $(".selector").igGridGroupBy("option", "emptyGroupByAreaContent"); // Set $(".selector").igGridGroupBy("option", "emptyGroupByAreaContent", "Put here columns to group by"); -
expandTooltip
- Type:
- string
- Default:
- ""
Specifies the expand indicator tooltip for grouped rows.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", expandTooltip: "Custom expand tooltip" }] }); // Get var opValue = $(".selector").igGridGroupBy("option", "expandTooltip"); // Set $(".selector").igGridGroupBy("option", "expandTooltip", "Custom expand tooltip"); -
expansionIndicatorVisibility
- Type:
- bool
- Default:
- true
Specifies if grouped rows will have an expander image that will allow end users to expand and collapse them.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", expansionIndicatorVisibility: true }] }); // Get var opValue = $(".selector").igGridGroupBy("option", "expansionIndicatorVisibility"); -
groupByAreaVisibility
- Type:
- enumeration
- Default:
- top
Sets the place in the grid where the groupBy area will be .
Members
- top
- Type:string
- the GroupBy area will be rendered above the grid headers .
- hidden
- Type:string
- the GroupBy area will not be rendered.
- bottom
- Type:string
- the GroupBy area will be rendered below the grid footer (and above the pager, if any).
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", groupByAreaVisibility: "bottom" }] }); // Get var opValue = $(".selector").igGridGroupBy("option", "groupByAreaVisibility"); -
groupByLabelWidth
- Type:
- number
- Default:
- null
By default, the column width for the header is taken. if this is specified it's used for all headers.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", groupByLabelWidth: 100 }] }); // Get var opValue = $(".selector").igGridGroupBy("option", "groupByLabelWidth"); // Set $(".selector").igGridGroupBy("option", "groupByLabelWidth", 100); -
groupedColumns
- Type:
- object
- Default:
- []
Specifies a list of grouped columns. You can use the option to retrieve a list of currently grouped
columns. The option is read-only, you can't set columns to be grouped by using it.Code Sample
// Get var groupedColumns = $(".selector").igGridGroupBy("option", "groupedColumns"); // Enumerates all grouped columns for(i = 0; i < groupedColumns.length; i++) { // Get column object groupedColumns.col // Get the sort order for this column groupedColumns.dir // Get the key of the grouped column groupedColumns.key // Get the key of the columnLayour if this is hierarchical view groupedColumns.layout }-
col
- Type:
- object
- Default:
- null
Column object for the column that is grouped.
Code Sample
// Get var groupedColumns = $(".selector").igGridGroupBy("option", "groupedColumns"); // Enumerates all grouped columns for(i = 0; i < groupedColumns.length; i++) { // Get column object groupedColumns.col } -
dir
- Type:
- enumeration
- Default:
- asc
sort order - ascending or descending.
Code Sample
// Get var groupedColumns = $(".selector").igGridGroupBy("option", "groupedColumns"); // Enumerates all grouped columns for(i = 0; i < groupedColumns.length; i++) { // Get the sort order for this column groupedColumns.dir } -
key
- Type:
- string
- Default:
- null
Key of the column that's grouped.
Code Sample
// Get var groupedColumns = $(".selector").igGridGroupBy("option", "groupedColumns"); // Enumerates all grouped columns for(i = 0; i < groupedColumns.length; i++) { // Get the key of the grouped column groupedColumns.key } -
layout
- Type:
- string
- Default:
- null
Key of the columnLayout, if the grid is hierarchical.
Code Sample
// Get var groupedColumns = $(".selector").igGridGroupBy("option", "groupedColumns"); // Enumerates all grouped columns for(i = 0; i < groupedColumns.length; i++) { // Get the key of the columnLayour if this is hierarchical view groupedColumns.layout }
-
groupedRowTextTemplate
- Type:
- string
- Default:
- ${key}: ${val} (${count})
Template for the grouped row's text, follows jQuery's templating guidelines.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", groupedRowTextTemplate: "Cost $ ${val} (Count: ${count})" } ] }); // Get var opValue = $(".selector").igGridGroupBy("option", "groupedRowTextTemplate"); // Set $(".selector").igGridGroupBy("option", "groupedRowTextTemplate", "Cost $ ${val} (Count: ${count})"); -
indentation
- Type:
- number
- Default:
- 30
Specifies the indentation for a grouped row. If several columns are grouped, the total indentation will grow.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", indentation: 50 } ] }); // Get var opValue = $(".selector").igGridGroupBy("option", "indentation"); // Set $(".selector").igGridGroupBy("option", "indentation", 50); -
initialExpand
- Type:
- bool
- Default:
- true
Specifies if after grouping, the grouped rows will be initially expanded or collapsed.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", initialExpand: false } ] }); // Get var opValue = $(".selector").igGridGroupBy("option", "initialExpand"); // Set $(".selector").igGridGroupBy("option", "initialExpand", false); -
labelDragHelperOpacity
- Type:
- number
- Default:
- 0.5
Specifies the opacity of the drag markup, while a column header is being dragged.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", labelDragHelperOpacity: 0.75 } ] }); // Get var opValue = $(".selector").igGridGroupBy("option", "labelDragHelperOpacity"); // Set $(".selector").igGridGroupBy("option", "labelDragHelperOpacity", 0.75); -
removeButtonTooltip
- Type:
- string
- Default:
- ""
Specifies the tooltip for the remove button.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", removeButtonTooltip: "Do not group by this column" } ] }); // Get var opValue = $(".selector").igGridGroupBy("option", "removeButtonTooltip"); // Set $(".selector").igGridGroupBy("option", "removeButtonTooltip", "Do not group by this column"); -
resultResponseKey
- Type:
- string
- Default:
- null
Specifies a key to get group by data from the response.
Code Sample
// Get var opValue = $(".selector").igGridGroupBy("option", "resultResponseKey"); // Set $(".selector").igGridGroupBy("option", "resultResponseKey", "Cost"); -
summarySettings
- Type:
- object
- Default:
- {}
Specifies the settings for GroupBy summaries.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", summarySettings: { multiSummaryDelimiter: " | ", summaryFormat: "#0.00" } }] }); // Get var opValue = $(".selector").igGridGroupBy("option", "summarySettings"); // Set $(".selector").igGridGroupBy("option", "summarySettings", { multiSummaryDelimiter: " | ", summaryFormat: "#0.00" });-
multiSummaryDelimiter
- Type:
- string
- Default:
- ,
Specifies the delimiter for multiple summaries, in case they are rendered inline in the grouped row.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", summarySettings: { multiSummaryDelimiter: " | " } }] }); // Get var summarySettings = $(".selector").igGridGroupBy("option", "summarySettings"); // Get the value of multiSummaryDelimiter summarySettings.multiSummaryDelimiter // Set // Get current summary settings and set a new value to multiSummaryDelimiter var summarySettings = $(".selector").igGridGroupBy("option", "summarySettings"); summarySettings.multiSummaryDelimiter = " | "; // Set the new value to the widget $(".selector").igGridGroupBy("option", "summarySettings", summarySettings); -
summaryFormat
- Type:
- string
- Default:
- #.00
By default, two digits are shown after the decimal place.
Code Sample
//Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", summarySettings: { summaryFormat: "#0.00" } }] // Get var summarySettings = $(".selector").igGridGroupBy("option", "summarySettings"); // Get the value of summaryFormat summarySettings.summaryFormat // Set // Get current summary settings and set a new value to summaryFormat var summarySettings = $(".selector").igGridGroupBy("option", "summarySettings"); summarySettings.summaryFormat = "#0.00"; // Set the new value to the widget $(".selector").igGridGroupBy("option", "summarySettings", summarySettings); });
-
type
- Type:
- enumeration
- Default:
- null
specifies the groupBy operation type - whether locally, or remotely.
Members
- local
- Type:string
- groupBy on the client-side.
- remote
- Type:string
- request.
Code Sample
//Initialize $(".selector").igGrid({ features: [ { name: "GroupBy", type: "local" } ] }); // Get var opValue = $(".selector").igGridGroupBy("option", "type"); // Set $(".selector").igGridGroupBy("option", "type", "local");
For more information on how to interact with the NetAdvantage for jQuery controls events, refer to
Using Events in NetAdvantage for jQuery
-
groupedColumnsChanged
- Cancellable:
- false
Event which is fired when the groupedColumns collection has changed
use args.owner in order to access the groupby widget object
use args.owner.grid to access the grid widget option
use args.groupedColumns to get a reference to the current groupedColumns
use args.key to get a reference to the current column's key that's being grouped
use args.layout to get a reference to the current layout object, if any
use args.grid to get a reference to the current child grid element, in case it's an hierarchical grid.Code Sample
//Bind after initialization $(document).delegate(".selector", "iggridgroupbygroupedcolumnschanged", function (evt, ui) { //return browser event evt.originalEvent; // Get a reference to the igGridGroupBy widget that fired the event ui.owner; // Get a reference to the igGrid widget to which the igGridGroupBy is bound ui.owner.grid; // Get a reference to the list of currently grouped columns ui.groupedColumns; // Get a reference to the current grouped column"s key ui.key; // Get a reference to the current layout object, if any ui.layout; // Get a reference to the current child grid element, in case it"s a hierarchical grid ui.grid; }); //Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", groupedColumnsChanged: function (evt, ui) { ... } }] }); -
groupedColumnsChanging
- Cancellable:
- true
Cance="true" Event which is fired when the grouped columns collection is about to change
use args.owner in order to access the groupby widget object
use args.owner.grid to access the grid widget option
use args.groupedColumns to get a reference to the current groupedColumns
use args.key to get a reference to the current column's key that's being grouped
use args.layout to get a reference to the current layout object, if any
use args.grid to get a reference to the current child grid element, in case it's an hierarchical grid.Code Sample
//Bind after initialization $(document).delegate(".selector", "iggridgroupbygroupedcolumnschanging", function (evt, ui) { //return browser event evt.originalEvent; // Get a reference to the igGridGroupBy widget that fired the event ui.owner; // Get a reference to the igGrid widget to which the igGridGroupBy is bound ui.owner.grid; // Get a reference to the list of currently grouped columns ui.groupedColumns; // Get a reference to the current grouped column"s key ui.key; // Get a reference to the current layout object, if any ui.layout; // Get a reference to the current child grid element, in case it"s a hierarchical grid ui.grid; }); //Initialize $(".selector").igGrid({ features: [{ name: "GroupBy", groupedColumnsChanging: function (evt, ui) { ... } }] });
-
destroy
- .igGridGroupBy( "destroy" );
Destroys the group by feature object.
Code Sample
$(".selector").igGridGroupBy("destroy"); -
groupByColumn
- .igGridGroupBy( "groupByColumn", key:string, [layout:string] );
Groups by a column.
- key
- Type:string
- Column Key key also be a number (assumed to be the col. index).
- layout
- Type:string
- Optional
- Layout is an optional parameter. if set it means the grouped column is not in the root level but is a child layout column.
Code Sample
$(".selector").igGridGroupBy("groupByColumn", "columnKey", "layout"); -
groupByColumns
- .igGridGroupBy( "groupByColumns" );
- Return Type:
- object
Returns the currently grouped columns.
Code Sample
var groupedColumns = $(".selector").igGridGroupBy("groupByColumns"); -
ungroupAll
- .igGridGroupBy( "ungroupAll" );
Ungroups all currently grouped columns.
Code Sample
$(".selector").igGridGroupBy("ungroupAll"); -
ungroupByColumn
- .igGridGroupBy( "ungroupByColumn", key:string, [layout:string] );
Ungroups by a column.
- key
- Type:string
- Column Key key also be a number (assumed to be the col. index).
- layout
- Type:string
- Optional
- Layout is an optional parameter. if set it means the grouped column is not in the root level but is a child layout column.
Code Sample
$(".selector").igGridGroupBy("ungroupByColumn", "columnKey", "layout");
-
ui-iggrid-dragmarkup
- Classes applied to the markup that's being dragged.
-
ui-iggrid-expandheadercellgb ui-iggrid-header ui-widget-header
- Classes applied to the special group by cell rendered in the header (the small empty first cell).
-
ui-widget-content ui-iggrid-footerextracell
- Classes which are applied to the extra rendered cell in the footer.
-
ui-iggrid-groupbyarea
- Classes applied to the group by area, where column headers can be dropped.
-
ui-iggrid-groupbyareahover
- Class applied when we are dragging a label and we are over a groupby area, before it's dropped.
-
ui-iggrid-groupbyareatext
- Classes applied to the text container in the group by area.
-
ui-iggrid-expandbuttongb ui-iggrid-groupexpandcell ui-icon ui-icon-plus
- Classes applied to the group by expander span element, when the group row is collapsed.
-
ui-iggrid-expandbuttongb ui-iggrid-groupexpandcell ui-icon ui-icon-minus
- Classes applied to the group by expander span element, when the group row is expanded.
-
ui-iggrid-expandcolumn
- Classes applied to the groupBy expander TD cell.
-
ui-icon ui-icon-circle-close ui-iggrid-groupbyremovebutton
- Classses applied to the remove button that appears for every column label that's dropped in the groupBy area. The button appears on hover.
-
ui-iggrid-groupedcolumnlabel ui-state-default
- Classes applied to the LI which is rendered in the groupBy area, when a column header is dropped there.
-
ui-iggrid-groupbylabelrightedge
- Classes applied to the right edge of a groupBy column label, when it's in the middle of the bread-crumb.
-
ui-iggrid-groupbylabelrightedgeend
- Classes applied to the right edge of the groupBy area bread-crumb labels, when there are no more labels to the right. so that it appears as triangle.
-
ui-iggrid-groupedcolumnlabeltext
- Classes applied to the text in the group by label.
-
ui-iggrid-groupbylayoutlabel
- Classes apppled to the text container, which specifies the columnLayout name in front of the groupBy column label, in case the grid is hierarchical.
-
ui-iggrid-groupedrow
- Classes applied to every group row TR.
-
ui-iggrid-nongrouprowemptycell
- Classes applied to every cell that's rendered in front of a data cell, which is not a grouped row. this is necessary so that data rows and grouped rows align well.
