Skip to content

Frozen cols/rows

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:

// Let the grid create the model
$grid->setColModel();
// Set some grid options
$grid->setGridOptions(array(
    "rowNum"=>10,
    "rowList"=>array(10,20,30),
    "rownumbers"=>true
));
// set frozen property
$grid->setColProperty("CustomerID", array(
    "frozen"=>true,
    "width"=>100
    )
);
$grid->setColProperty("ShipName", array(
    "width"=>150,
    "frozen"=>true
    )
);

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

// Call the frozen cols method
$grid->callGridMethod('#grid', '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.

Destroy

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

// Destroy the frozen cols method
$grid->callGridMethod('#grid', 'destroyFrozenColumns');

or using JavaScript

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. Suppose we have defined a button with id=mybutton in the HTML content

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

$grid->setJSCode($setfrozen);

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 recommended 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 - see the example above. 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
  • When keyboard navigation is enabled (bindKeys method)
  • When aria or excel like grid is activated (setAriaGrid method)

Frozen Rows

It is quit easy for developers to make some rows frozen/locked within jqGrid. The locked rows do not scroll out of view when users moving vertically across the grid.

As of version 5.7 jqGrid support frozen rows. In the time of writing this documentation the support of frozen rows is very limited. Please refer to limitations

Setup

To setup the frozen rows property it is needed to call the method setFrozenRows 

$grid->callGridMethod('#grid', 'setFrozenRows', array( $options=array() ));

where the options is a array with the following default properties.

$options = array(
    "first" => 0,
    "last" => 0,
    "rowids" =>array(),
    "saveFirstLastId" =>false,
    "classes" =>"
)
  • first - integer- parameter which specify how many index row(s) from the top current view should be locked. 1 means first row, 2 means first and second rows and etc.
  • last -integer- parameter which specify how many index row(s) from the bottom current view should be locked. 1 means last row, 2 means last and penultimate rows and etc.
  • rowids - array- if set this array should contain the ids of the rows which will be locked.
  • saveFirstLastId - boolean - this parameter work only if first or last parameters are set. In case of true the ids of the locked rows will be saved when for first time the method is executed and will stay on top regardless of sorting paging an etc.
  • classes - string - this string will be added as class of the locked row(s)

Note

If for some reason the first and/or last and/or rowids parameters are set, the higher priority has the rowids parameter, then first and the last one

Destroy

To destroy the frozen rows use destroyFrozenRows method.

// Destroy the frozen rows method
$grid->callGridMethod('#grid', 'destroyFrozenRows', array($deep=false));

or using JavaScript

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

where deep is a logical parameter which if is set to true, removes all data related to frozen rows. By default this parameter is false.

Limitations

The frozen rows is a new feature and hence it has some limitations which in the future will be removed. Below are the limitations for the frozen rows. The frozen rows will not be initialized when:

  • when subGrid is enabled
  • when treeGrid is enabled
  • when cellEdit is enabled
  • when data grouping is enabled
  • when virtual scrolling is enabled (scroll: 1)
  • when frozen columns are enabled

If one of these modules are activated and you for some reason call frozenRows method you should expect unexpected behaviors.