Frozen Columns


It is quit easy for developers to make some columns frozen/locked within jqGrid. The locked columns do not scroll out of view when users moving horizontally across the grid. This is quite useful when you dealing with wide table with some fields should be visible permanently.

Setup

First you will need to setup which columns will be frozen/locked. This is done in colModel setting the property frozen:true. Below is a correct setup:

...
jQuery("#grid").jqGrid({
...
 colModel: [
   {name: 'name', width: 70, frozen:true },
   {name: 'invdate', width: 80, align: 'center', sorttype: 'date',
    formatter: 'date',  frozen:true},
   {name: 'amount', width: 75, formatter: 'number', align: 'right'},
   {name: 'tax', width: 75, formatter: 'number', align: 'right'},
   {name: 'total', width: 75, formatter: 'number', align: 'right'},
   {name: 'closed', width: 75, align: 'center', formatter: 'checkbox'},
   {name: 'ship_via', width: 100, align: 'center', formatter: 'select',
      edittype: 'select', editoptions: {value: 'FE:FedEx;TN:TNT;IN:Intim'}},
   {name: 'note', width: 70, sortable: false}
 ],
 ...
});

After this you will need to call the method which is responsible to do this:

jQuery("#grid").jqGrid('setFrozenColumns');

The method has no parameters.

Note

The frozen property should be set one after other. If there is a missing frozen property in the sequence then the last position which meet this criteria will be used.

In the example below only the first column will be locked.

...
jQuery("#grid").jqGrid({
...
 colModel: [
   {name: 'name', width: 70, frozen:true },
   {name: 'invdate', width: 80, align: 'center', sorttype: 'date'}
   {name: 'amount', width: 75, align: 'right', frozen : true},
   {name: 'tax', width: 75, formatter: 'number', align: 'right'},
   {name: 'total', width: 75, formatter: 'number',  align: 'right'},
   {name: 'closed', width: 75, align: 'center', formatter: 'checkbox'}
   {name: 'ship_via', width: 100, align: 'center', formatter: 'select',
      edittype: 'select', editoptions: {value: 'FE:FedEx;TN:TNT;IN:Intim'}},
   {name: 'note', width: 70, sortable: false}
 ],
 ...
});
jQuery("#grid").jqGrid('setFrozenColumns');

Destroy

It is possible to destroy the frozenColumns in the grid using the method destroyFrozenColumns. This method restores the grid configuration before calling the setFrozenColums

jQuery("#grid").jqGrid('destroyFrozenColumns');

Dynamic setup

It is possible to set the frozen columns dynamically. In this case it is needed to call first destroyFrozenColumns method, setup new frozen properties and call again setFrozenColumns.

Below example tell how to do this, making the invdate column frozen:

jQuery("#mybutton").click(function(){
   jQuery("#grid")
   .jqGrid('destroyFrozenColumns')
   .jqGrid('setColProp','invdate', {frozen:true})
   .jqGrid('setFrozenColumns')
   .trigger('reloadGrid', [{current:true}]); // optional
});

Notes, Limitations

When possible the setFrozenColumns method should be called as last method of the sequence dealing with the initial loading of the grid. By example if you first call frozenColumns and then filterToolbar method this will make a inconsistency of the locked columns and the rest of columns. This is valid for all methods dealing with the changing the grid presentation like toolbars, group headers and etc.

The frozen columns need a horizontal scroll bar. In order this to happen it is needed to set the option shrinkToFit set to false and set explicit the width of the grid. Optionally the autowidth option should be set to true in order to fit to parent container.

In case when the visual presentation of the grid should be changed dynamically - i.e by example the filterToolbar is set dynamically or any other similar action - it is needed first to call the method destroyFrozenColumns, make your changes and call again setFrozenColumns in your script. Note that this is valid only if the visual change of grid is made.

The service columns for the row numbers (grid options rownumbers : true ) and the multiselect column (grid option multiselect: true) are set by default to frozen:true. This way it is not needed to set these property to frozen.

The following limitations are valid when deal with frozen columns - i.e the frozen columns will not set-up.

  • When TreeGrid is enabled
  • When SubGrid is enabled
  • When cellEdit is enabled
  • When inline edit is used - the frozen columns can not be edit.
  • When sortable columns are enabled - grid parameter sortable is set to true or is function
  • When scroll is set to true or 1
  • When Data grouping is enabled