Selection Overview (igGrid)

Topic Overview

Purpose

This topic explains the selection functionality of the igGrid™ control.

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.

In this topic

This topic contains the following sections:

• Overview
• Selection persistence
• Enabling Selection
• Select/Unselect a Cell/Row
  • Select a Row
  • Unselect a Row
  • Get Selected Rows
  • Select a Cell
  • Unselect a Cell
  • Get Selected Cells
  • Clear Selection
• Selection Modes
  • Single Selection
  • Multiple Selection
  • Row Selection
  • Cell Selection
• Selection Events
• Selection Properties
• Selection CSS Classes
• Keyboard interactions
• Related Content
  • Topics
  • Samples

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:

• Arbitrary selections are possible by dragging the mouse to form rectangles around selected files as well.

Figure 1: The igGrid control with continuous selection by dragging with the mouse

Figure 2: The igGrid control with multiple cell selection enabled

Selection Persistence

Persisting Selection between igGrid states is made easy in version 14.1 and in fact replaces the previous default behavior.

Note Selection persistence is true by default. This is a breaking change.

When you enable igGridSelection you are already using it in a persist mode which means that any rows or cells being selected will remain selected after you interact with other features of the grid (such as sorting or filtering a column) or simply data binding.

Selection persistence is implemented for igHierarchicalGrid too.

The following sample demonstrates the persistance capabilities of the Selection feature.

Persisting depends on the feature’s ability to unambiguously distinguish rows and columns from one another.

As row indexes are not stable and therefore unusable for this purpose, igGridSelection will use either the user-defined primary key of the grid or will generate pseudo-unique identifiers for each row based on the corresponding record’s property values.

These internal identifiers take a small portion of the grid rendering time to generate and there is a small chance that two records in a large data set can produce the same identifier.

Note It’s advisable that applications which have selection persistence enabled provide an explicit, unique primary key.

If you would like to retain the current behavior of selection being cleared after user interacts with the grid, you can do this by disabling the feature through the persist option as shown in the code snippet below:

In JavaScript:

features: [
  { 
     name: “Selection”, 
     persist: false 
  }
]

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.min.js"></script>
<script type="text/javascript" src="jquery-ui.min.js"></script>
<script type="text/javascript" src="infragistics.core.js"></script>
<script type="text/javascript" src="infragistics.lob.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="infragistics.util.js"></script>
<script type="text/javascript" src="infragistics.util.jquery.js"></script>
<script type="text/javascript" src="infragistics.dataSource.js"></script>
<script type="text/javascript" src="infragistics.ui.shared.js"></script>
<script type="text/javascript" src="infragistics.ui.grid.framework.js"></script>
<script type="text/javascript" src="infragistics.ui.grid.selection.js"></script>

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/Row

Users may select cells/rows by using the mouse or keyboard. To select cells/rows 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:

• Click for single selection
• Click and drag for multiple, continuous selection
• Shift-click for multiple, continuous selection
• Ctrl-click for multiple discontinuous selection

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:

• From anywhere in your application:

  In Javascript:

  $("#grid1").bind("iggridselectionrowselectionchanged", handler);
  

For more information regarding handling events please refer to the topic :

Using Events in Ignite UI for jQuery

• By specifying the event name as an option when you initialize the Selection feature (this is not case sensitive, as opposed to the first way of binding events):

  In Javascript:

  {
     name: 'Selection',
     mode: 'cell',
     multipleSelection: true,
     cellSelectionChanging: handler,
     <other Selection options>
  }
  

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> ,    
    id:<primaryKey value or null if undefined>,    
    index: <index of the grid row TR>
}

Grid cell object:

{
    element: <cell TD>,
    row: <parent of the cell, that is the row TR>,
    rowId: <primaryKey value or null if undefined>,
    index: <col index>,
    rowIndex: <the row index>,
    columnKey: <column key>
}

The Selection feature exposes the following client-side events:

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.

Selection CSS Classes

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

Keyboard interactions

When a specific row is selected, the following key interactions are available:

• UP: Moves selection to the row above the currently selected row. If selection is on the first row then the selection will move to the last row.
• DOWN: Moves selection to the row below the currently selected row. If selection is on the last row then the selection will move to the first row.
• SPACE/ENTER: Selects/Deselects the active row.

When multiple selection is enabled:

• SHIFT+UP/DOWN: Allows selection of multiple rows while holding shift.
• CTRL+ UP/DOWN: Moves the active row without changing selection. Allows selection of multiple rows via the keyboard by moving the active row and using SPACE to select/deselect the currently active row.

When a specific cell is selected, the following key interactions are available:

• UP: Moves selection to the cell above the currently selected cell. If selection is on a cell from the first row then selection moves to the cell from the in the same column on the last row.
• DOWN: Moves selection to the row below the currently selected row. If selection is on the last row then the selection will move to the first row.
• LEFT: Moves selection to the cell left of the current cell. If selection is on the first cell of the row then selection moves to the last cell of the previous row. If selection is on the first cell of the first row then selection moves to the last cell of the last row of the grid.
• RIGHT: Moves selection to the cell right of the current cell. If selection is on the last cell of the row then selection moves to the first cell of the next row. If selection is on the last cell of the last row then it moves to the first cell of the first row.
• SPACE/ENTER: Selects/Deselects the current cell. Also in igHierarchicalGrid scenario, if the currently selected active cell is the one containing the expand/collapse buttons this will also expand/collapse the child grid of the row.

In igHierarchicalGrid scenario selection skips going into the child grids with the UP/DOWN/LEFT/RIGHT arrow keys by default (see the skipChildren option).

Related Content

Topics

• igGrid Overview
• Paging (igGrid)
• Filtering (igGrid)
• Sorting Overview (igGrid)

Samples

• Selection