Infragistics(R) NetAdvantage(R) jQuery
igGrid Selection
E-mail your feedback on this topic.

Glossary Item Box

The selection feature enables the selection of the rows and cells of the igGrid™ control. Its functionality closely follows the Microsoft® Windows Explorer™ and Microsoft® Excel™ selection and activation behaviors.

Grid selection comes with robust client-side-event support, providing the necessary tools for managing the control’s behavior at run time.

Overview

Selection is implemented as a jQuery UI widget and as such follows the lifecycle of any jQuery UI widget.

The selection feature of the igGrid control is responsible for both selection and activation. Grid “activation” can mean several things. On one hand, activation refers to keyboard navigation. If activation is turned off, keyboard activation is disabled. On the other hand, the specific active style is applied on cells and rows (without being accompanied by selection style) when CTRL is held down and the arrow keys are pressed, similar to Windows Explorer navigation.

Cells may also be selected in a more traditional sense. Cells can be selected either with the mouse or with the keyboard. When cells are selected with the mouse, multiple selections are available. For instance, while holding the CTRL key is down, multiple non-continuous files are selected. While holding the SHIFT key, multiple continuous files are selected. Other variations of mouse-based selection include:

Keyboard navigation is available using any of the ARROW keys: LEFT ARROW, RIGHT ARROW, DOWN ARROW, and UP ARROW. Variations of keyboard navigation include:

Note: To enable drag-select functionality on touch devices, you need to include the jQuery Mobile library on your page.

Figure 1: The igGrid control with multiple row selection enabled

Figure 2: The igGrid control with multiple cell selection enabled

Enabling Selection

In order to get started with Selection, you first need to include the necessary JavaScript and CSS dependencies. The easiest way to do this is to use the combined/minified version of the scripts and styles:

In HTML:

<link type="text/css" href="infragistics.theme.css" rel="stylesheet" />
<link type="text/css" href="infragistics.css" rel="stylesheet" />
<script type="text/javascript" src="jquery-1.4.4.min.js"></script>
<script type="text/javascript" src="jquery-ui.min.js"></script>
<script type="text/javascript" src="jquery.tmpl.js"></script>
<script type="text/javascript" src="infragistics.js"></script>

If you would like to include only the minimal Infragistics scripts necessary for selection, you can do so by referencing:

In HTML:


<script type="text/javascript" src="ig.util.js"></script>
<script type="text/javascript" src="ig.dataSource-en.js"></script> <script type="text/javascript" src="ig.dataSource.js"></script> <script type="text/javascript" src="ig.ui.shared.js"></script> <script type="text/javascript" src="ig.ui.grid-en.js"></script> <script type="text/javascript" src="ig.ui.grid.framework.js"></script> <script type="text/javascript" src="ig.ui.grid.selection-en.js"></script> <script type="text/javascript" src="ig.ui.grid.selection.js"></script>

*-en.js files contain localized strings for various parts of the UI. If you would like to localize the feature in a different language, replace the selection -en.js with your localized version. You only need to change the values in the file; the keys must remain the same.

After including the necessary scripts, enabling the selection feature of the igGrid is as simple as adding an object with the name Selection to the Features array of the control. By default, the selection mode is set to Row, allowing row selection. Activation is also enabled by default.

The following code snippets demonstrate enabling the functionality:

In Javascript:

$("#grid1").igGrid({
   dataSource: products,
   responseDataKey: 'Records',
   tabIndex: 1,
   features: [{
      name: 'Selection',
      mode: 'row',
      multipleSelection: true,
      activation: true
   }]
});

In ASPX:

<%=
   Html.
   Infragistics().
   Grid(Model).
   ID("grid1").
   PrimaryKey("ProductID").
   Features(features => {
      features.
      Selection().
      Mode(SelectionMode.Row).
      MultipleSelection(true).
      Activation(true);
   }).
   Virtualization(false).
   DataSourceUrl(Url.Action("SelectionApiGetData")).
   DataBind().
   Render()%>

In Razor:

@{
   Html.
   Infragistics().
   Grid(Model).
   ID("grid1").
   PrimaryKey("ProductID").
   Features(features => {
      features.
      Selection().
      Mode(SelectionMode.Row).
      MultipleSelection(true).
      Activation(true);
   }).
   Virtualization(false).
   DataSourceUrl(Url.Action("SelectionApiGetData")).
   DataBind().
   Render()
}

Select/Unselect a Cell

Users may select cells by using the mouse or keyboard. To select cells in code, you can use the exposed properties and methods of the igGridSelection component of the igGrid control. A few of the possible actions are listed in the following examples:

Select a Row

In Javascript:

$('#grid1').igGridSelection('selectRow', indexOfRowToSelect);

Unselect a Row

In Javascript:

$('#grid1').igGridSelection('deselectRow', indexOfRowToDeselect);

Get Selected Rows

This variation of the method returns a JSON array with the available properties that include element and index.

In Javascript:

var rows = $('#grid1').igGridSelection('selectedRows');

Select a Cell

In Javascript:

$('#grid1').igGridSelection('selectCell', rowIndex, columnIndex);

Unselect a Cell

In Javascript:

$('#grid1').igGridSelection('deselectCell', rowIndex, columnIndex);

Get Selected Cells

This variation of the method returns a JSON array with the available properties that include element, row, index, rowIndex and columnKey.

In Javascript:

var cells = $('#grid1').igGridSelection('selectedCells');

Clear Selection

In Javascript:

$('#grid1').igGridSelection('clearSelection');

Selection Modes

The igGrid control’s selection features allow for single and multiple selection of cells on the grid.

Single Selection

With single selection enabled, you can click a cell or a row to select it.

Multiple Selection

With multiple selection enabled, you can do the following:

Row Selection

To enable row selection, you must enable the selection feature by setting the mode to “row,” or by leaving it unset (row selection is the default behavior) to select rows in the grid.

After enabling row selection, users can select a row by clicking on any of the row’s cells. You can also select rows in code by using the exposed methods as demonstrated in the Cell Selection examples previously listed in this document.

Cell Selection

To enable cell selection, you must set the selection mode set to “cell” when initializing the selection behavior.

There are several ways to select a cell after enabling cell selection. First, users can select a cell by clicking on it or by navigating to it with the keyboard. You can also select and unselect cells in code by using the methods demonstrated in the Cell Selection examples previously listed in this document.

Selection Events

The igGrid control supports the most common and expected events for the selection feature. You can bind to the control’s row and cell selection changing and changed events (with the former being cancellable). Events are raised when active cell or roll changes are available, making every selection action manageable in code.

You can bind to client-side events in two different ways:

Note: You should “live” instead of “bind” if selection is not yet instantiated.

Then your “handler,” assuming it is called like this, should be defined the following way:

In Javascript:

function handler(event, args) {

}


The args is an object that is explained in detail below, respectively, for each event.

Grid row object:

{element:<element of the grid row TR> , index: <index of the grid row TR>}

Grid cell object:

{element: <cell TD>, row: <parent of the cell, that is the row TR>, index: <col index>, rowIndex: <the row index>, columnKey: <column key>}

The Selection feature exposes the following client-side events:

Event Name Argument (args) Parameters
rowSelectionChanging

row: Current selected grid row

selectedRows: Array of currently selected rows

owner: Reference to the selection widget object

manual: True if selection was changed programmatically; false otherwise

startIndex: Index of start row (multiple selection) – optional.

endIndex: Index of end row (multiple selection) – optional

rowSelectionChanged Same as rowSelectionChanging except that now “selectedRows” contains the new rows added to the selection. Note: This event does not have the startIndex and endIndex properties.
cellSelectionChanging

cell: Current selected cell

firstRowIndex: Index of first selected row

lastRowIndex: Index of last selected row

firstColumnIndex: Index of first selected column

lastColumnIndex: Index of last selected column

Note: The last four properties are only used with continuous multiple selection.

selectedCells: Array of currently selected cells

owner: Reference to the Selection widget object

manual: True if selection was changed programmatically; false otherwise

cellSelectionChanged Same as the above except that firstRowIndex, lastRowIndex, firstColumnIndex, and lastColumnIndex are not present any more and selectedCells now contains the new selection as well.
activeCellChanging

cell: Reference to the cell that is about to become active

This event is cancelable.

activeCellChanged cell: Reference to the new active cell
activeRowChanging

row: Reference to the row that is about to become active

This event is cancelable.

activeRowChanged row: the new active row.
Note: When continuous selection is performed by pressing the SHIFT key, events are fired only once for the whole batch.

Selection Properties

The following table contains more information about the supported properties for the Selection feature.

Property Name Type and Default Value Description
multipleSelection Boolean (default: False) Enables/disables multiple selection
mouseDragSelect Boolean (default: True) Allows continuous selection by dragging with the mouse
mode String (default: ‘row’) Can be either row or cell
wrapAround Boolean (default: True) When the first or last rows or cells are reached, continue from the opposite direction
activation Boolean (default: True) Enables/disables cell and row activation – active style
touchDragSelect Boolean (default: True) Enables / disables selection via continuous touch event - only applicable for cell selection and touch-supported environments.
multipleCellSelectOnClick Boolean (default: False) If true multiple selection of cells is done as if CTRL is being held. the option is disregarded if mode is set to row. this option is useful for enabling multiple discountinued selection on touch environments.

Selection CSS Classes

You can use the following table should you wish to customize the look of the Selection feature.

Group of CSS classes List of actual CSS classes Description
selectedCell

ui-iggrid-selectedcell

ui-state-active

Classes applied on every selected cell.
selectedRow

ui-iggrid-selectedrow

ui-state-active

Classes applied on every selected row.
selectedHeader

ui-iggrid-selectedheader

ui-state-active

Column selection (currently does not work)
activeCell

ui-iggrid-activecell

ui-state-focus

Classes applied on every active cell.
activeRow

ui-iggrid-activerow

ui-state-focus

Classes applied on every active row.
 
Related Topics