Pre-General Availability: 2018-3-9

Widget: grid

QuickNav

Options

Events

Methods

grid

A jQuery UI widget that implements a navigable data grid that supports selection and editing. It follows the DHTML Style Guide and WAI-ARIA design pattern for a grid box with these differences:

  • In row selection mode the Shift and Ctrl modifiers work like a list control. In cell selection mode discontinuous ranges are not supported so Shift-F8 is not supported.
  • Ctrl+Home/End is not supported.
  • In edit/actionable mode you can tab out of the grid at the beginning or end.

The markup expected by this widget is simply an empty div. The grid displays and optionally edits data stored in an apex data model. If the grid is editable then the div must be proceeded by a div with class "u-vh" (to visually hide the contents)that contains each of the rendered column items. Each column item needs to be wrapped in a div with class a-GV-columnItem. The markup looks like this:

   ≶div class="a-GV-columnItemContainer u-vh" aria-hidden="true">
       ≶div class="a-GV-columnItem">column item markup goes here≶/div>
       ...
   ≶/div>
todo consider changing a-GV-columnItemContainer to a-ColumnItem[s|Container] Grid widget functional css takes care of hiding the column items off screen.

The grid widget has a number of configuration options. See the comments below on the options property of the widget initialization. Some of the configuration options are described in more detail in the following topics.

Editing:
The grid can be editable or not editable. This is controlled by the editable option. If not editable then no UI is provided to do any editing, however it will still respond to any changes to the model data. When the grid is editable it has two modes; navigation mode and editing mode. The distinction is mainly for the purpose of keyboard behavior. In navigation mode keyboard keys move among the grid cells. In editing mode most keys are passed through to the edit controls. Edit mode pertains to cell editing only. Other kinds of edits such as deleting rows is possible as long as the grid is editable. The editable property can be changed after the grid is created provided the necessary column items are available on the page. See the model documentation for how it can be used to provide fine grained control over what kinds of edits are allowed. The column definition can specify columns that are read-only. For a cell to be editable the grid must be editable, the row must be editable (as determined by the model), the column configuration must specify elementId and readonly must not be true and the cell field metadata must not have a checksum (ck) property.

Column Edit Items:
When the grid is editable and a column can be edited, it is a column item that does the editing. Column items are essentially the same as page items except they edit a column value rather than a page item. See elementId in list of column properties below.

Column configuration:
Columns are configured with the columns option. The value is an object that maps a column name to a column definition object. The column name is a friendly name (likely related to a database column ex: FIRST_NAME) that may be used in template substitutions. The properties are the column/property names. The property value is a column definition. This column structure is likely shared with the model and upper layer widgets or controller code as well. The column definition properties are: elementId: {string} Id of DOM element used to edit cells in this column or null if not editable heading: {string} The text of the column header. Allows markup label: {string} The text of the column. Does not allow markup. Used by control break headers. headingAlignment: {string} One of "start", "end", "center", "left", "right". Determines how the heading text is aligned default is "center". alignment: {string} Determines how the cell content is aligned. Takes same values headingAlignment. Optional with no default. headingCssClasses: {string} CSS classes applied to the column heading cell columnCssClasses: {string} CSS classes applied to each cell in this column cellTemplate: {string} Optional. An HTML template that defines the cell content. The template syntax is the same as APEX server side templates. See apex.util.applyTemplate for template syntax. The substitutions are column names from this column configuration and they are replaced with data values from the current row. escape: {boolean} If false the column value may contain trusted markup otherwise the column value is escaped. seq: {number} Determines the order of the column among all the others. Lower numbers come first. width: {number}, optional column width noStretch: {boolean} optional. If true the column width will not stretch to fill available space as the grid resizes The user can still adjust the width. By default columns will stretch. groupName: {string} optional name of column group useGroupFor: {string} Optional. If not present or if the string contains "heading" then the group given in groupName will be used usedAsRowHeader If true the column is an accessible row header. noHeaderActivate: {boolean} if true the column header does not support activation. default is false sortDirection: {string} "asc" if the data is sorted by this column ascending, "desc" if the data is sorted by this column descending null or not present or undefined if the data is not sorted by this column sortIndex: {number} Optional. Only applies if sortDirection is given. The order in which this column is sorted 1 = first, 2 = second, etc. canSort: {boolean} if true the column can be sorted by the user. This controls if the header sort buttons are shown or if the keyboard sort keys work. The grid does not actually do the sorting. The sortChange event/callback is triggered to let the controller or parent widget know to do sorting. controlBreakIndex: {number} Optional. The order in which this column is sorted for the purpose of control breaks. Starting at 1. controlBreakDirection: {string} "asc" if the control break data is sorted by this column ascending, "desc" if the control break data is sorted by this column descending null or not present or undefined if the column is not a control break hidden: {boolean} If true the column is not rendered frozen: {boolean} If true the column is frozen (does not h-scroll). Only the start most columns can be frozen. The last column cannot be frozen. readonly: {boolean} If true the column cannot be edited linkText: {string} Optional. The anchor content. Allows markup. Allows substitutions just like the cellTemplate property. If not given the rendered display value of this column cell is used as the content. If the display value of the column is empty then the link URL is used. To display a link, at least one of linkTargetColumn or the cell field metadata url property must must be given. Note: if the cell is editable it is always the data value of the cell that is edited. So if you want to edit the link text is it best to omit linkText and use linkTargetColumn. linkTargetColumn: {string} Optional. The name of the column that contains the anchor href. If not given the href comes from the cell field metadata url property. If there is no url property then this column/cell is not a link. linkAttributes: {string} Optional. Additional anchor attributes. Allows substitutions just like the cellTemplate property. Ignored unless a link is present. isRequired {boolean} If true the column is indicated as required by adding is-required class to the column header This should correspond with the required setting of the underlying editable column item. helpid {string} Help id for the column. If present pressing the help key Alt+F1 will display the help text for the field. The "property" property is added to the definition. Its value is the column name (property from the columns map. Column methods: getColumns refreshColumns setColumnWidth hideColumn showColumn freezeColumn unfreezeColumn moveColumn Column Group definitions: heading: {string} The text of the column header. Allows markup. label: {string} [not used] Same as heading but markup not allowed. headingAlignment: {string} One of "start", "end", "center", "left", "right". Determines how the heading text is aligned default is "center". parentGroupName: {string} Optional name of the parent column group.

Selection

The grid supports both row and cell range selection. For row selection the grid supports either single or multiple selection. Rows can be selected even for grids that are not editable. For multiple selection standard keyboard modifiers Shift and Ctrl are always supported. In addition the rowHeaderCheckbox option allows for checkbox style selection behavior.

Context Menus

The grid has easy integration with the menu widget to provide context menu support. The grid#contextMenu option is used to provide a menu widget options object. When the contextMenu option is used the menu#event:beforeOpen event/callback ui argument has these additional properties:

  • menuElement: The menu jQuery object.
  • grid: This grid jQuery object.
  • selection: A jQuery object with the selected rows at the time the menu was opened.
  • selectedRecords: An array of the selected model records at the time the menu was opened. Only if selectCells is false.
  • selectedRange: The range information returned by getSelectedRange. Only if selectCells is true.

Also the menu#event:afterClose event/callback will automatically focus the grid if the menu action didn't take the focus and the ui argument has these additional properties:

  • menuElement: The menu jQuery object.
  • grid: This grid jQuery object.

If using the contextMenu option the grid#contextMenuId option can be used to give the menu element an ID. This is useful if other code must refer to the menu element or widget.

You can reference an already existing menu widget by specifying the grid#contextMenuId in place of the grid#contextMenu option.

If for any reason you don't want to use the menu widget, the grid#contextMenuAction option allows you to respond to mouse or keyboard interactions that typically result in a context menu. Specifically Right Mouse click (via contextmenu event), Shift-F10 key (via keydown event) and the Windows context menu key (via contextmenu event). The original event is passed to the contextMenuAction function. The event object can be used to position the menu. If you implement your own menu it is best if you put focus back on the grid using the grid#focus method when the menu closes (unless the menu action directs focus elsewhere).

Only one of grid#contextMenuAction and grid#contextMenu or grid#contextMenuId can be specified. The contextMenu and contextMenuId options can only be set when the grid is initialized and it can't be changed. The contextMenuAction cannot be set if the contextMenu or contextMenuId options were given when the grid was created. The context menu only applies to grid cells - not to header cells.

Keyboard End User Information

KeyAction
Escape Closes the sub menu or if at the top level closes the menu. When the menu closes focus returns to the element that opened the menu, if any.
Up Arrow todo
Down Arrow Move focus to the next item wrapping around at the bottom.
Enter or Space Activate the menu item. The effect depends on the type of menu item. It may perform some action, cause navigation, open a sub menu, or toggle or choose a setting. With the exception of opening a sub menu after the activation the menu closes and focus returns to the element that opened the menu, if any, and unless the action explicitly set focus.
Right Arrow On a sub menu item opens the sub menu. In a menu bar moves focus to the next menu wrapping at the end and opening it if a menu is already open.
Left Arrow In a sub menu closes the sub menu. In a menu bar moves focus to the previous menu wrapping at the beginning and opening it if a menu is already open.
Tab The behavior depends on the menu#tabBehavior option.
printable character Sets focus to the next menu item with a label that starts with the character.
todo - Currently not visible Required columns or columns which are needed as parent for Cascading LOVs and which don't have a default value specified will automatically be displayed when switching into Edit Mode. - "If a row is a parent row in a parent – child relationship, all child rows will automatically be marked for deletion too. Reverting the delete will also automatically revert the deletion of the child rows. In the child Interactive Grid, it's not possible to revert single deleted rows if the parent row is marked for deletion." Multiple models and grids are involved how is this coordinated? - for inline edit items how to for example check the checkbox on click, drop down the select list on click, open the date picker/color picker on click. - what if total width of all frozen columns [nearly] exceeds the client area width? This can happen because of browser window or container resize. Should columns automatically be unfrozen until there is enough room to scroll? - scroll pagination; with no total, interaction with control breaks This widget requires some functional CSS.
Since:
  • 5.0

Options

allowCopy :boolean

If true the selection can be copied to the clipboard using the browsers copy event.

Type:
  • boolean
Default Value:
  • true

allowDelete :boolean

Only applies if editable is true. If false then can't use delete key to delete a row.

Type:
  • boolean
Default Value:
  • true

allowEditMode :boolean

Only applies if editable is true. If false then can't go in or out of edit mode using mouse or keyboard.

Type:
  • boolean
Default Value:
  • true

allowInsert :boolean

Only applies if editable is true. If false then can't use Insert key to add a row.

Type:
  • boolean
Default Value:
  • true

columnSort :boolean

If true the mouse and keyboard can be used in column headings to adjust the sort order. The grid doesn't actually do any sorting. Something external to the grid must do the actual sorting by handling the sortchange event and updating the model.

Note the sort order can still adjusted external to the grid even if this is false.

Type:
  • boolean
Default Value:
  • true

columnSortMultiple :boolean

If true multiple columns can be sorted using Shift key modifier. This only applys if columnSort is true.

Type:
  • boolean
Default Value:
  • true

contextMenu :Object

A menu widget options object use to create the context menu.

Only specify one of contextMenu or contextMenuId and contextMenuAction. If none of contextMenu, contextMenuId or contextMenuAction are specified there is no context menu.

Type:
  • Object
Default Value:
  • null

contextMenuAction :function

A callback function that is called when it is time to display a context menu. function( event ) The function is responsible for showing the context menu. It is given the event that caused this callback to be called.

In most cases it is simpler and more consistent to use the contextMenu option. Only specify one of contextMenu or contextMenuId and contextMenuAction. If none of contextMenu, contextMenuId or contextMenuAction are specified there is no context menu.

Type:
  • function
Default Value:
  • null

contextMenuId :string

If option contextMenu is given then this is the element id to give the context menu created. This allows other code to interact with the created context menu widget.

If option contextMenu is not given then this is the element id of an existing menu widget.

Type:
  • string
Default Value:
  • null

multiple :boolean

If true multiple rows can be selected otherwise only a single row can be selected.

Type:
  • boolean
Default Value:
  • false

multipleCells :boolean

Only applies while selectCells is true. If true then a range of cells can be selected otherwise only a single cell is selected. The default is to allow a range of cells to be selected.

Type:
  • boolean
Default Value:
  • true

reorderColumns :boolean

If true the mouse and keyboard can be used in column headings to reorder the columns or column groups.

Note the column order can still be changed external to the grid.

Type:
  • boolean
Default Value:
  • true

resizeColumns :boolean

If true the mouse and keyboard can be used in column headings to adjust the width of columns.

Note the column widths can still be changed external to the grid.

Type:
  • boolean
Default Value:
  • true

selectCells :boolean

When true select cells otherwise select rows. The default is to select rows.

Type:
  • boolean
Default Value:
  • false

showNullAs :string

Text to display when the value is null or empty string

Type:
  • string
Default Value:
  • "-"

stickyTop :boolean|function

Determine if the column header will stick to the top of the page as it scrolls.

Only applies if hasSize is false. If false the column header will not stick to the page. If true or a function the column header will stick to the top of the page using the stickyWidget If a function then it is passed to the stickyWidget as the top option.

Type:
  • boolean | function
Default Value:
  • false

Events

selectionchange

Triggered when the selection state changes. It has no additional data.
Properties:
Name Type Description
event Event jQuery event object.
Examples

Initialize the grid with the selectionChange callback specified:

$( ".selector" ).grid({
    selectionChange: function( event ) {}
});

Bind an event listener to the gridselectionchange event:

$( ".selector" ).on( "gridselectionchange", function( event ) {} );

Methods

activateRow(pCell, pCallback)

Parameters:
Name Type Description
pCell
pCallback

copyDownSelection(pColumnsopt, pCallbackopt)

Copies cell values from columns in the first selected row to all the other selected rows within the same columns. If pColumns is given only cells in the specified columns are copied down. Only cells that can be written will be copied to. If the selection mode is row selection, only visible columns that don't have noCopy column property equal true are filled.

Parameters:
Name Type Attributes Description
pColumns array <optional>
 An optional array of column names to copy down. The columns must be in the selection, visible, and writable.
pCallback function <optional>
 A no argument function that is called when the copy down operation is complete.

debugCellEdit(value)

This method is for developer debugging only. When developing a item plug-in that is to be used in a grid cell it can be difficult to debug on CSS styling because as soon as the cell looses focus the item is moved in the DOM to a hidden area. Calling this with a true argument to turn on cell edit debugging leaves the item in the cell after it looses focus so that the DOM and styles can be inspected with browsers developer tools. This is not effective for end user use. Because the cell is not fully deactivated it can affect editing in general. Call it again with false to turn off cell edit debugging.
Parameters:
Name Type Description
value boolean
Example
From the console
var view$ = ... // this is the grid widget jQuery object.
view$.grid("debugCellEdit", true)
// do your debugging
view$.grid("debugCellEdit", false)

fillSelection(pFillValue, pColumnsopt, pCallbackopt)

Fills all cells in the current selection with the value pFillValue. If pColumns is given only cells in the specified columns are filled. Only cells that can be written will be filled. If the selection mode is row selection, only visible columns that don't have noCopy column property equal true are filled.

Parameters:
Name Type Attributes Description
pFillValue string The value to fill cells with.
pColumns array <optional>
 An optional array of column names to fill. The columns must be in the selection, visible, and writable.
pCallback function <optional>
 A no argument function that is called when the fill operation is complete.

focus()

Give focus to the grid. Focus is given to the last element that had focus.

freezeColumn(pColumn)

Freeze the given column. Also calls refreshColumns and will render the whole grid.
Parameters:
Name Type Description
pColumn column name or column definition object to freeze.

getActiveCellFromColumnItem(pItem) → {jQuery}

Given a column item return the cell for that column item in the current active row. If pItem is not a column item or if there is no active row return null.
Parameters:
Name Type Description
pItem Element
Returns:
cell corresponding to pItem
Type
jQuery

getColumns() → {Array}

Get the column definitions in order.
Returns:
Array of column definition objects.
Type
Array

getRecords(pRows) → {Array}

Given an array of jQuery row objects return the underlying data model records. The return value of getSelection is an appropriate value for pRows. However it need not contain tr elements from both the frozen and un-frozen areas.
Parameters:
Name Type Description
pRows array of jQuery objects representing grid rows.
Returns:
array of records from the model corresponding to the grid rows
Type
Array

getSelectedRange() → {Object}

Returns the selected cell range or null if there are no cells selected. For this method to work the option selectCells must be true.
Properties:
Name Type Description
columns Array An array of column names one for each selected column. The column name is null for the row header pseudo column.
recordIds Array An array of record ids one for each selected row.
values Array An array rows. Each row is an array of column values.
Returns:
Information about the range of selected cells or null if no cells selected.
Type
Object

getSelectedRecords() → {Array}

Return the underlying data model records corresponding to the current selection. Note: If option persistSelection is true then the selected records could span multiple pages and getSelectedRecords returns a different selection from getSelection which can only return elements from the current page. To get just the records that correspond to getSelection when this option is true use: $().grid("getRecords", $().grid("getSelection"))
Returns:
array of records from the model corresponding to the selected grid rows
Type
Array

getSelection() → {Array}

Return the current selection. The return value depending on the selectCells option.

If selectCells is true, return the current selected range as an array of rows. Each row is a jQuery object containing the selected column cells.

If selectCells is false, return the currently selected rows as an array of jQuery objects each item in the array is a row. When there are frozen columns (or even just a frozen row header) each jQuery item in the array contains two tr elements. One for the frozen columns and one for the non-frozen columns.

Returns:
array of jQuery row objects.
Type
Array
Examples

The following example processes a row selection (selectCells is false).

var i, rows = $( "#mygrid" ).grid( "getSelection" );
for ( i = 0; i < rows.length; i++ ) {
    // note rows[i].length === 2 if there are frozen columns and 1 otherwise
    rows[i].addClass("foo"); // this adds a class to both tr elements in the case where there are frozen columns
    rows[i].children().each(function() {
        // do something with each column
    }
}

The following example processes a cell range selection (selectCells is true).

var i, rows = $( "#mygrid" ).grid( "getSelection" );
for ( i = 0; i < rows.length; i++ ) {
    // note rows[i].length is the number of columns in the range selection.
    rows[i].addClass("foo"); // this adds a class to all cells in the selected columns of this row
    rows[i].each(function() {
        // do something with each column cell
    }
}

gotoCell(pRecordId, pColumnopt)

Put focus in the cell given by pRecordId and pColumn. This is used to focus rows or cells that have errors. This will scroll or change pages as needed to focus the cell. The record must be in the model. The row containing the cell is selected. If pColumn is null then the first column is focused which may be the row selection header.
Parameters:
Name Type Attributes Description
pRecordId string the record id of the row to go to.
pColumn string <optional>
 column in the record row to go to.

hideColumn(pColumn)

Hide the given column. Also calls refreshColumns and will render the whole grid.
Parameters:
Name Type Description
pColumn column name or column definition object to hide.

inEditMode() → {boolean}

Determine if grid is in edit mode rather than navigation mode.
Returns:
true if in edit mode and false otherwise.
Type
boolean

moveColumn(pColumn, pNewPosition)

Move the given column to the new position. Also calls refreshColumns and will render the whole grid. Triggers columnReorder event.
Parameters:
Name Type Description
pColumn column name or column definition object to move.
pNewPosition number index into the array returned by getColumns where the column will be moved to.

moveColumnGroup(pLevel, pOriginalPosition, pNewPosition)

Move a column group from one position to another. This moves all the columns associated with the group to the new position. Triggers columnReorder event for each column moved.
Parameters:
Name Type Description
pLevel number the level (starting with zero as the top most level) of the group
pOriginalPosition number original position of the column group
pNewPosition number new position of the column group

refresh(pFocusopt)

Refreshes the grid with data from the model. This method is rarely needed because it is called automatically when the model changes, widget options change, or when pagination or column related methods are called.

Try to persist the selection. xxx What was selected may not exist in the grid after refresh. First try to select the same records.
Parameters:
Name Type Attributes Description
pFocus boolean <optional>
 if true put focus in the grid, if false don't. If undefined/omitted maintain focus if the grid already has focus.

refreshColumns()

Let the grid know that column metadata has changed so that the next time it is refreshed columns will be rendered. Call this method after any column metadata has changed external to this widget. Refresh must be called after this but typically this happens due to the model refresh notification.

resize()

Call this method anytime the container that the grid is in changes its size. For performance it is best to call this after the size has changed not continuously while it is changing.

selectAll(pFocusopt, pNoNotifyopt)

Select all rows. This has no effect if the multiple or selectAll options are not true. This only applies to the current page xxx or what has been rendered so far???? xxx if pagination is not scroll then it applies to the whole page otherwise it applies to what is in the scroll viewport
Parameters:
Name Type Attributes Description
pFocus boolean <optional>
 if true the first cell of the selection is given focus.
pNoNotify boolean <optional>
 if true the selection change event will be suppressed

setColumnWidth(pColumn, pWidth)

Sets the width of the given column. Triggers columnResize event.
Parameters:
Name Type Description
pColumn column name or column definition object to set the width on.
pWidth number width in pixels to set the column too.

setEditMode(pEditMode)

Set the current edit mode. Should only be used if the grid is editable. Triggers modeChange event.
Parameters:
Name Type Description
pEditMode boolean If true enter edit mode if false enter navigation mode.

setSelectedRecords(pRecords, pFocusopt, pNoNotifyopt) → {integer}

Select the grid rows that correspond to the given data model records. Depending on pagination the records may not actually be in view or rendered at this time even if they exist in the underlying data model or on the server.
Parameters:
Name Type Attributes Description
pRecords Array array of data model records to select
pFocus boolean <optional>
 if true the first cell of the selection is given focus
pNoNotify boolean <optional>
 if true the selection change event will be suppressed
Returns:
Count of the rows actually selected or -1 if called before the grid data is initialized or if selectCells option is true.
Type
integer

setSelection(pRows, pFocusopt, pNoNotifyopt)

Set the selected rows of the grid.
Parameters:
Name Type Attributes Description
pRows Array an array of jQuery row objects such as the return value of getSelection or a jQuery object containing one or more rows (tr elements) or columns (td elements) from this grid. xxx or array of jQuery column objects
pFocus boolean <optional>
 if true the first cell (in pRows) of the selection is given focus.
pNoNotify boolean <optional>
 if true the selection change event will be suppressed

showColumn(pColumn)

Show the given column. Also calls refreshColumns and will render the whole grid.
Parameters:
Name Type Description
pColumn column name or column definition object to show.

unfreezeColumn(pColumn)

Unfreeze the given column. Also calls refreshColumns and will render the whole grid.
Parameters:
Name Type Description
pColumn column name or column definition object to unfreeze.