Interactive grid
¶

As of version 5.4 Guriddo jqGrid enables users to navigate the information or interactive elements it contains using directional navigation keys, such as arrow keys, Home , and End. As a generic container widget that offers flexible keyboard navigation, it can serve a wide variety of needs. It can be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.

Keyboard Interaction¶

The documentation of chapter Keyboard Interaction is taken from here

The following keys provide grid navigation by moving focus among cells of the grid. Implementations of grid make these key commands available when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab.

Right Arrow: Moves focus one cell to the right. Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row. If focus is on the last cell in the grid, focus does not move.
Left Arrow: Moves focus one cell to the left. Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. If focus is on the first cell in the grid, focus does not move.
Down Arrow: Moves focus one cell down. Optionally, if focus is on the bottom cell in the column, focus may move to the top cell in the following column. If focus is on the last cell in the grid, focus does not move.
Up Arrow: Moves focus one cell up. Optionally, if focus is on the top cell in the column, focus may move to the bottom cell in the previous column. If focus is on the first cell in the grid, focus does not move.
Page Down (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move.
Page Up (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move.
Home: moves focus to the first cell in the row that contains focus. Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the first cell in the grid.
End: moves focus to the last cell in the row that contains focus. Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the last cell in the grid.
Control + Home (optional): moves focus to the first cell in the first row.
Control + End (Optional): moves focus to the last cell in the last row.

Note

When the above grid navigation keys move focus, whether the focus is set on an element inside the cell or the grid cell depends on cell content. See Whether to Focus on a Cell or an Element Inside It.
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. If this functionality is needed, see Editing and Navigating Inside a Cell.
If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as control + End, may move focus to the last row in the DOM rather than the last available row in the back-end data. In this case it is recommended to reset the navigation before adding new content and then set it again. See below configuration

Whether to Focus on a Cell Or an Element Inside It¶

For assistive technology users, the quality of experience when navigating a grid heavily depends on both what a cell contains and on where keyboard focus is set. For example, if a cell contains a button and a grid navigation key places focus on the cell instead of the button, screen readers announce the button label but do not tell users a button is present.

There are two optimal cell design and focus behavior combinations:

A cell contains one widget whose operation does not require arrow keys and grid navigation keys set focus on that widget. Examples of such widgets include link, button, menubutton, toggle button, radio button (not radio group), switch, and checkbox.
A cell contains text or a single graphic and grid navigation keys set focus on the cell.

While any combination of widgets, text, and graphics may be included in a single cell, grids that do not follow one of these two cell design and focus movement patterns add complexity for authors or users or both. The reference implementations included in the example section below demonstrate some strategies for making other cell designs as accessible as possible, but the most widely accessible experiences are likely to come by applying the above two patterns.

Editing and Navigating Inside a Cell¶

While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to perform actions like operate a combobox or move an editing caret inside of a cell. The user may need keys that are used for grid navigation to operate elements inside a cell if a cell contains:

Editable content.
Multiple widgets.
A widget that utilizes arrow keys in its interaction model, such as a radio group or slider.

Following are common keyboard conventions for disabling and restoring grid navigation functions.

Enter: Disables grid navigation and:
If the cell contains editable content, places focus in an input field, such as a textbox. If the input is a single-line text field, a subsequent press of Enter may either restore grid navigation functions or move focus to an input field in a neighboring cell.
If the cell contains one or more widgets, places focus on the first widget.
F2:
If the cell contains editable content, places focus in an input field, such as a textbox. A subsequent press of F2 restores grid navigation functions.
If the cell contains one or more widgets, places focus on the first widget. A subsequent press of F2 restores grid navigation functions.

When grid navigation is disabled, conventional changes to navigation behaviors include:

Escape: restores grid navigation. If content was being edited, it may also undo edits.
Right Arrow or Down Arrow: If the cell contains multiple widgets, moves focus to the next widget inside the cell, optionally wrapping to the first widget if focus is on the last widget. Otherwise, passes the key event to the focused widget.
Left Arrow or Up Arrow: If the cell contains multiple widgets, moves focus to the previous widget inside the cell, optionally wrapping to the first widget if focus is on the last widget. Otherwise, passes the key event to the focused widget.
Tab: moves focus to the next widget in the grid. Optionally, the focus movement may wrap inside a single cell or within the grid itself.
Shift + Tab: moves focus to the previous widget in the grid. Optionally, the focus movement may wrap inside a single cell or within the grid itself.

Configuration¶

To configure the keyboard navigation in Guriddo jqGrid use the following method:

jQuery("#grid").jqGrid('setAriaGrid', options);

Where

#grid is the id of the table element as used in the jqGrid.

The method should be called after the grid initialization. When this method is called we set navigation on the grid header cells, grid cells and grid pager (if present) cells. Using Tab to focus on the grid is the first visible header cell. Moving from header to body cell is done with Tab key or click on a certain body cell or call a method - see below. The same apply when moving from body cell to a pager cell. Using Shit + Tab reverses the order of moving.
When a header cell is focused and Enter key is pressed a sorting apply depending on the sortable parameter.
When a pager cell is focused and Enter key is pressed the appropriate action is raised.

options¶

This is a object with following properties and default values.

options = {
  header : true,
  body : true,
  pager : true,
  onEnterCell : null,
  customCellAction : null,
  onKeyCheck : null,
  onHeaderKeyCheck : null
};

header - this Boolean option enables disables keyboard navigation in the header cells in the grid.
body - this Boolean option enables disables the keyboard navigation in body cells in the grid
pager - this Boolean option enables disables the keyboard navigation in pager cells in the grid
onEnterCell(id, iRow, iCol, event) - function to be called when Enter key is pressed of the focused body cell. Parameters passed to this function are:
- id - the row id of the focused cell
- iRow - the row index of the focused cell
- iCol - the column index of the focused cell
- event - the keydown event passed to this cell.
customCellAction(id, iRow, iCol, event) - function to be called when the user press key different from the predefined one up, down and etc. Parameters passed to this function are:
- id - the row id of the focused cell
- iRow - the row index of the focused cell
- iCol - the column index of the focused cell
- event - the keydown event passed to this cell.
onKeyCheck(id, iRow, iCol, event) - function to be called every time the key is pressed on the body cell. If the event return false nothing happen. Parameters passed to this function are:
id - the row id of the focused cell
iRow - the row index of the focused cell
iCol - the column index of the focused cell
event - the keydown event passed to this cell.
onHeaderKeyCheck(index, event) - function to be executed when the navigation is on the header cells (a key is pressed)
- index the index of the cell which is selected
- event - the keydown event

Note

To disable navigation if editing module is used (cell edit, inline edit) use the grid option navigationDisabled and set it to true after calling the one of these methods and after editing set this option again to false.

Calling this method add keyboard shortcuts and additional events in the grid. To restore the state and disable keyboard navigation call the method:

jQuery("#grid").jqGrid('resetAriaGrid', params);

Where

#grid is the id of the table element as used in the jqGrid.

params¶

This is a object with following properties and default values.

options = {
  header : true,
  body : true,
  pager : true
};

header - this Boolean option enables disables resetting the keyboard navigation in the header cells in the grid.
body - this Boolean option enables disables resetting the keyboard navigation in body cells in the grid
pager - this Boolean option enables disables resetting the keyboard navigation in pager cells in the grid

Methods¶

The following methods are added for easy and separate keyboard navigation of different grid parts.

Body Methods¶

ariaBodyGrid( object options )
Add keyboard navigation on body data cells.

parameters

object options - set of options with default values

options = {
  onEnterCell : null,
  onKeyCheck : null,
  customCellAction : null
};

onEnterCell(id, iRow, iCol, event) - function to be called when Enter key is pressed of the focused body cell. Parameters passed to this function are:
- id - the row id of the focused cell
- iRow - the row index of the focused cell
- iCol - the column index of the focused cell
- event - the keydown event passed to this cell.
onKeyCheck(id, iRow, iCol, event) - function to be called every time the key is pressed on the body cell. If the event return false nothing happen. Parameters passed to this function are:
id - the row id of the focused cell
iRow - the row index of the focused cell
iCol - the column index of the focused cell
event - the keydown event passed to this cell.
customCellAction(id, iRow, iCol, event) - function to be called when the user press key different from the predefined one up, down and etc. Parameters passed to this function are:
- id - the row id of the focused cell
- iRow - the row index of the focused cell
- iCol - the column index of the focused cell
- event - the keydown event passed to this cell.

returns
jqGrid object

focusBodyCell( [integer focusRow], [integer focusCol])
Dynamically focus a cell into the body by given index of row and column. If these parameters are omitted the last selected cell is focused.

*parameters
- integer focusRow - the index (Not the id) of the row of the cell to be focused
- integer focusCol - the index of the column of the cell to be focused

returns
jqGrid object

resetAriaBody()
Restore the grid state and disable keyboard navigation in the body
*parameters

returns
jqGrid object

Header Methods¶

ariaHeaderGrid( object options )
Add keyboard navigation on the header cells. Note that this method work only on the headers cells defined in colModel and not on cells created with groupingHeader method. When a header cell is focused and Enter key is pressed a sorting apply depending on the sortable parameter.

parameters

options = {
    onHeaderKeyCheck : null
}

onHeaderKeyCheck(index, event) - function to be executed when the navigation is on the header cells (a key is pressed)
- index the index of the cell which is selected
- event - the keydown event

returns
jqGrid object

focusHeaderCell( [integer index] )
Dynamically focus a cell into the header by given index of column. If this parameter is omitted the last selected cell is focused.

*parameters
- integer index - the index of the column of the header cell to be focused

returns
jqGrid object

resetAriaHeader()
Restore the grid state and disable keyboard navigation in the header

*parameters

returns
jqGrid object

ariaPagerGrid()
Add keyboard navigation on the pager cells if the pager is defined.

parameters

returns
jqGrid object

focusPagerCell( [integer index] )
Dynamically focus a cell into the pager by given index of column. If this parameter is omitted the last selected cell is focused.

*parameters
- integer index - the index of the button of the pager to be focused

returns
jqGrid object

resetAriaPager()
Restore the grid state and disable keyboard navigation in the pager

*parameters

returns
jqGrid object

Interactive grid¶

Keyboard Interaction¶

Whether to Focus on a Cell Or an Element Inside It¶

Editing and Navigating Inside a Cell¶

Configuration¶

options¶

params¶

Methods¶

Body Methods¶

Header Methods¶

Pager Methods¶

Interactive grid
¶