jQuery Hierarchical Grid - Enabling paging, sorting & filtering in the grid

Jordan Tsankov / Thursday, January 26, 2012

If you have worked with our jQuery Hierarchical Grid, you most certainly have respect for the sheer amount of data you can load it with. You can have multiple levels of grids all connected to a single entry in your hierarchical grid. The amount of information available at any given point in time can become overwhelming – this is where any features that ease up the presentation of your jQuery Hierarchical Grid help. Sorting, filtering and paging are such features and they help you organize the data available in a meaningful way.

Let's get on with it !

The basics

Activating these features on an hierarchical grid is just as simple as doing it in a regular grid. Here’s a brief reminder on how to do it:

   1: grid.igHierarchicalGrid({
   2:     dataSource: source,
   3:     dataSourceType: "json",
   4:     features: [
   5:     {
   6:         name: "Filtering",
   7:         type: "local",
   8:         mode: "simple",
   9:         inherit: true
  10:     },
  11:     {
  12:         name: "Paging",
  13:         type: "local",
  14:         pageSize: 3,
  15:         inherit: true
  16:     },
  17:     {
  18:         name: "Sorting",
  19:         type: "local",
  20:         inherit: true
  21:     }]
  22: });

And you’ve successfully enabled paging, sorting and filtering on the whole hierarchical grid. Now once we’ve taken the first step, let’s elaborate on some points that are specific to the hierarchical grid.

Inherit

While looking at the code snippet above, you maybe noticed on lines 9, 15 and 20 that there is a property declared that you may not be familiar with. What it does is that, when enabled, it will pass the according feature along to any child grids. Let me show what I mean:

By having the following setup, you enable all three features on both the root level grid as well as any sub-grids present within it.

   1: grid.igHierarchicalGrid({
   2:     dataSource: source,
   3:     dataSourceType: "json",
   4:     width: 800,
   5:     columns: [
   6:         { headerText: "Project ID", key: "ProjectId", dataType: "number" },
   7:         { headerText: "Name", key: "Name" },
   8:         { headerText: "Start Date", key: "StartDate", dataType: "date" },
   9:         { headerText: "End Date", key: "EndDate", dataType: "date" }
  10:     ],
  11:     columnLayouts: [
  12:     {
  13:         caption: "Developers",
  14:         key: "Developers",
  15:         responseDataKey: "Records",
  16:         autoGenerateColumns: false,
  17:         autoGenerateLayouts: false,
  18:         columns: [
  19:             { headerText: "Developer ID", key: "DeveloperId", dataType: "number" },
  20:             { headerText: "Project ID", key: "ProjectId", dataType: "number" },
  21:             { headerText: "Name", key: "Name" },
  22:             { headerText: "Position", key: "Position" },
  23:             { headerText: "Hide Date", key: "HireDate", dataType: "date" },
  24:             { headerText: "Salary", key: "Salary", dataType: "number", format: "currency" }
  25:  
  26:         ]
  27:     }],
  28:     features: [
  29:     {
  30:         name: "Filtering",
  31:         type: "local",
  32:         mode: "simple",
  33:         inherit: true
  34:     },
  35:     {
  36:         name: "Paging",
  37:         type: "local",
  38:         pageSize: 3,
  39:         inherit: true
  40:     },
  41:     {
  42:         name: "Sorting",
  43:         type: "local",
  44:         inherit: true
  45:     }]
  46: });

The columnLayout property you see in the code above is one of the hierarchical grid’s defining properties – it specifies a behavior for the next level of entries, contained in a separate grid. What you could also do is initialize a new set of features specific for this column layout, but we’ll get back to that in a few. The snippet above will produce the following result:

inherit_all

With a single declaration of those three features, we enable them on every possible level of our hierarchical grid. Now, bear in mind the following things when using the “inherit” property:

  • Inherit is only meant to be set on the root-level grid. While you are technically able to set it at any level within the grid, the results can not be accounted for.
  • Inherit is false by default. Once you enable it, it will stay enabled. You cannot turn it off without reinitializing the grid.
  • Inherit only cascades downwards – i.e. goes down in hierarchy. If for some reason you enable inherit on a level that is not the root, do not expect ancestors to have the inherit features.
  • While inherit will carry over all of the feature’s settings, if there are any columnSettings defined, they will not be inherited.

So, it turns out that even though the inherit property is useful, it’s not what you should always be using since it is not that flexible. If you have a hierarchical grid which spans many levels deep, and you want to enforce a set of general rules – go on, inherit will do just that and it will work flawlessly. If you, on the other hand, require a different set of features for every level in your hierarchical grid, there is another way to do it.

ColumnLayouts features

When the need calls for more specific feature definitions, you will need to do it in the respective layer’s columnLayouts property. What you need to remember is that, basically, columnLayouts represents a grid. Every time you define columnLayouts, you’re defining a grid at a particular level in your hierarchy grid. With that in mind, it’s possible to initialize a features property inside every columnLayouts. Here’s what you should know about setting features in this manner:

  • A columnLayouts feature will override an inherit feature.
  • When using columnLayouts, make sure to specify primary key/foreign key pairs for each level of the hierarchy ( if any actually exist ). If your input data doesn't have primary/foreign key pairs, you will only be able to bind the igHierarchicalGrid to them once. If you want to use load on demand or any feature in the igHierarchicalGrid however, you will need to re-design your input data to contain pairs of primary/foreign keys.
  • Defining features in columnLayouts lets you use the columnSettings property for each feature and be sure that it will be in effect. We mentioned earlier that inherit will not work properly with columnSettings.

An example of providing proper key pairs can be seen in my files.

Conclusion

While the paging, sorting and filtering features operate in the same way as with a normal grid, this blog post addressed some helpful facts about setting these features up in a jQuery Hierarchical Grid. We went through “covering more ground” by using inherit and also being more specific with columnLayouts.

There is an example solution that shows both points in action. You can see exactly how to state the primary/foreign key pairs, as well as use inherit together with grid-specific features. Get the sample by clicking here.

InfragisticsHG_sorting_filtering_paging.zip