“Outlook Group By” in Infragistics jQuery Hierarchical Grid

Atanas Dyulgerov / Thursday, April 5, 2012

Defining hierarchies through grouping by a specific property (Outlook style) was introduced for the first time as a CTP in Infragistics’ NetAdvantage for jQuery 2011.2. This feature is now stable in 2012.1 and you can fully benefit from it. This article will show you how to use it.

Notice how the products in this snapshot are organized by the color. You can achieve such grouping in two ways – through the UI, dragging the column you want to be basis for the grouping to the special group by area or though code behind. The first option if as easy as setting three lines of code for the specific feature in the grid initialization. In the code behind you need to do a bit more than that. Read on to see exactly how.

Before we start and show how to enable the feature we need to setup a hierarchical grid with some data. For the demonstration purposes we are going to use the adventure works database. We have a variable defined in a separate js script file that holds all the data. The simplest way to create a grid that uses that data is to employ the Infragistics loader – you just point it to a folder with js files and folder of css files (provided with the NetAdvantage product) and it will load everything you need. The following code shows the working grid without GroupBy.

  1. <html>
  2.     <head>
  3.         <title>NetAdvantage for jQuery Samples</title>
  5.         <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" type="text/javascript"></script>
  6.         <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.13/jquery-ui.min.js" type="text/javascript"></script>
  8.         <script type="text/javascript" src="js/adventureWorksProductsInventories.js"></script>
  10.         <script type="text/javascript" src="js/infragistics.loader.js"></script>
  11.         <script type="text/javascript">
  12.             $.ig.loader({
  13.                 scriptPath: "js/",
  14.                 cssPath: "css/",
  15.                 resources: "igHierarchicalGrid.GroupBy,igHierarchicalGrid.Paging"
  16.            });
  17.         </script>
  19.         <script type="text/javascript">
  20.             $.ig.loader(function () {
  21.                 $("#grid").igHierarchicalGrid({
  22.                     initialDataBindDepth: 1,
  23.                     dataSource: productsInventories,
  24.                     dataSourceType: 'json',
  25.                     responseDataKey: "Records",
  26.                     loadOnDemand: false,
  28.                     autoGenerateColumns: false,
  29.                     autoGenerateLayouts: true,
  30.                     columns: [
  31.                         { key: "ProductID", headerText: 'Product ID', width: "100px" },
  32.                         { key: "Name", headerText: 'Product Name', width: "250px" },
  33.                         { key: "ProductNumber", headerText: 'Product Number', dataType: "string", width: "150px" },
  34.                         { key: "Color", headerText: 'Color', dataType: "string", width: "100px" },
  35.                     ]
  36.                 });
  37.             });
  39.         </script>
  40.     </head>
  41.     <body>
  42.         <div id="grid" />
  43.     </body>
  44. </html>

A quick walkthrough the code and then we’re gonna enable the group by feature. The first two scripts we add are the jquery and jquery ui libs. They are required for the whole thing to work. Then the js file that holds our data. The following two script objects are the Infragistics loader code – you just have to specify where the css and js folders are and which resources you want to load.

The last script is the initialization of the grid itself. We provide the variable for the adventureWorksProductsInventory.js file that holds the data as data source, provide a little more info to make it readable and then we specify a few columns that we want to show. The layouts we can leave to be autogenerated. The result of this code is this:

Now that we have a working grid we can finally add the GroupBy feature. We can do that immediately after the column definitions.

  1. features: [
  2.     {
  3.         name: "GroupBy",
  4.         type: "local",
  5.         groupByAreaVisibility: "top",
  6.         inherit: true,
  7.         groupByLabelWidth: "250px",
  8.         labelDragHelperOpacity: 0.2,
  9.         removeButtonTooltip: "Ungroup Column",
  10.         emptyGroupByAreaContent: "Drag here columns to group by",
  11.         //  Group by the Color column initially
  12.         columnSettings: [
  13.             { columnKey: "Color", isGroupBy: true },
  14.             { columnKey: "Name", allowGrouping: false }
  15.         ]
  16.     }
  17. ]

The required parameters are name and type. If you provide just them you will have a row on top of your grid that has a link “select columns” which opens the following modal window:

If you click the group by link next to a column that column will be used to setup the grouping.

The position of the group by area can be controlled by the groupByAreaVisibility. Possible values are “top” and “bottom”.

Inherit is the parameter which controls if the settings for this particular feature should be propagated to the sub layouts. It is not directly related to the GroupBy feature.

The next several parameters control how the GroupBy area should look. You can set the width of each label that represents a grouping column, how transparent the label that you drag to be, what the labels should say, etc.

The last thing that you can do here is setting the initial group by columns. This is controlled by the column settings parameter. You can fine tune each column there – you can disable grouping permanently for specific columns or mark them as grouped on load.

The GroupBy functionality extends much beyond the ui interface that we just described and set up. The IG Hierarchical Grid provides a bunch of events that you can hock up to and execute custom logic. They are accessible in the same place where we just set the other parameters. Here is an example that shows a message after a new column has been added to the grouping:

  1. groupedColumnsChanged: function (e, args) {
  2.     alert("The columns were changed");
  3. }

A list with events that you can use follows:

  • groupedColumnsChanging
  • groupedColumnsChanged
  • modalDialogMoving
  • modalDialogClosing
  • modalDialogClosed
  • modalDialogOpening
  • modalDialogOpened
  • modalDialogContentsRendering
  • modalDialogContentsRendered
  • modalDialogButtonApplyClick
  • modalDialogButtonResetClick
  • modalDialogGroupingColumn
  • modalDialogGroupColumn
  • modalDialogUngroupingColumn
  • modalDialogUngroupColumn
  • modalDialogSortGroupedColumn


In addition to those events the grid provides a method that can manually do the grouping. Its called the igGridGroupBy. For example you can remove all grouping with a single line of code programmatically.

  1. $("#grid").igGridGroupBy("ungroupAll");

Other possible usages are grouping or ungrouping by specific column:

  1. $("#grid").igGridGroupBy("groupByColumn", column);
  2. $("#grid").igGridGroupBy("ungroupByColumn", column);

With that I conclude this article. I hope you have found it interesting and useful. Have a great day!