Selection/ Multiselection


Selection in jqGrid is enabled by default, and the user can select some row by a single click. When the row is selected a previously selected row is deselected and the new one is selected. When the selection is done we can query the selected row by row id and by index.

When the row is selected it is colored with another color depending on the settings on styleUI css object definition. The name of this property is highlight and is in common property. For Bootstrap the default class definition is:

styleUI : {
  ...
  Bootstrap : {
    common : {
      ...
      highlight : "success",
      ...
    ...
    }
    ...
  }
}

Muti selection is way to select a multiple rows at once and do some actions with the selected rows.

Below are considered all the options and events related to selection and multiselection.

Definitions

By default jqGrid is configured to select a single row. To get the id of the selected row use the following code:

var selectedRow =  $("#grid_id").jqGrid('getGridParam', 'selrow');

The code above will return the id of the selected row. If there is no selected row a null is returned.

To get the index of the selected row use the following code.

var selectedRow =  $("#grid_id").jqGrid('getGridParam', 'selrow');
var selectedIndex $("#grid_id").jqGrid('getInd', selectedRow);

To enable multiselection use the following code:

$("#grid_id").jqGrid({
  ...
  multiselect : true,
  ...
});

When this option is set a new column automatically is added to the colModel. The name of this internally defined column is cb It is displayed at first column at left when the direction is set to ltr and at right if it is set to rtl. The cell associated with this column is a checkbox and determine the sate of the row - if it is checked, the row is selected and if not the row is not selected. Additionally to this a new check box is build at grid header row. When click on this check box all the current visible rows in the grid are selected/deselected at once

This column by default is: not sortable, resizable and searchable. It is fixed, frozen and can be show/hide with the appropriate methods and with columnChooser one.

The default width of this column is 30 pixels. To change it use the option multiselectWidth

$("#grid_id").jqGrid({
  ...
  multiselect : true,
  multiselectWidth : 50,
  ...
});

To get the selected rows when a multiselect is enabled do:

var selectedRows =  $("#grid_id").jqGrid('getGridParam', 'selarrrow');

The selectedRows variable is array which every element is a selected row id. If notihing is selected the array is empty - i.e selectedRows.length = 0;

Options and events

Again with the multiselect and multiselectWidth we have other related options.

multiboxonly if this optiopn is set to true and the multiselect is true the multiselection is possible only when the checkbox for the appropriate row is clicked. Clicking on any row outside this checkbox will deselect all rows and select the current clicked only.

multikey This string parameter makes sense only when the multiselect option is set to true. Defines the key which should be pressed when we make multiselection. The possible values are: shiftKey - the user should press Shift Key, altKey - the user should press Alt Key, and ctrlKey - the user should press Ctrl Key. When this parameter is set multibox parameter does not have effect.

multimail if this options is set to true and the multiselect is on, the selection is like Yahoo and Google mail. Multiselection is done so that the multiboxonly parameter is set to true with additional properties. Select one row. After this click on Shift key and checkbox only cell to select a row below or above of the selected row with two or more positions. All the rows in this interval will be selected. If the user click on another row using the check box this row is selected too. If the click is not on the checkbox all the rows are deselected and the current is selected. It is possible to select multiple groups using the approach described above. To deselect a rows press the shiftKey and click on the one of the previously selected row - the group will be deselected.
When multimail is on it is possible to set multiboxonly parameter to true. In this case when click outside the checkbox and there are selected rows - nothing is happen - the multiselection is done only when a checkbox is click and when shiftKey is pressed and checkbox is clicked.

Caution

When multimail is set to true the onSelectRow event is executed only when multiboxonly is true and we click on row outside the checkbox. In all other cases the onSelectRow is not executed.

deselectAfterSort By default this option is true and determine how to process the selected rows (in multiselect mode) when sorting is performed. If it is false the selection is preserved after sorting a column, if it is true the selected rows are reset and sorting is done. This option is valid only if the datatype is local or loadonce parameter is set to true.

onSelectAll( selected, status)
jqGridSelectAll(event, selected, status)
This event fires when multiselect option is true and you click on the header checkbox to select/deselect current grid rows. The parameters are as follow:

  • array selected - array of the selected rows (rowid's). This parameter contain the id of the selected rows in case there is selection and is empty array when nothing is selected.
  • boolean status - variable determining the status of the header check box - true if checked, false if not unchecked.

editselected this parameter is available in editRow method or in navGrid method in editing options. When this option is set to true and multiselect is on too the form editing is possible only on the selected rows. Note that when using navigator buttons in form editing to navigate through the rows only the selected one are selected skipping the not selected one.

Notes and Limitations

The following rules are valid when multiselct is on

  • it is possible to use subGrid
  • it is possible to use grouping
  • it is disabled when treeGrid is enabled.
  • it is disabled when scroll option is set to 1 or true