Component: ojDataGrid

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

Options


Binding Attributes
Context Objects
Sub-ID's

oj. ojDataGrid extends oj.baseComponent

Version:
  • 3.2.0
Since:
  • 0.6

JET DataGrid Component

Description:

A JET DataGrid is a themable, WAI-ARIA compliant component that displays data in a cell oriented grid. Data inside the DataGrid can be associated with row and column headers. Page authors can customize the content rendered inside cells and headers.

Data

The JET DataGrid gets its data from a DataGridDataSource. There are several types of DataGridDataSource that are provided out of the box:

  • oj.ArrayDataGridDataSource - Use this when the underlying data is a static array. The ArrayDataGridDataSource supports both single array (in which case each item in the array represents a row of data in the DataGrid) and two dimensional array (in which case each item in the array represents a cell in the DataGrid). See the documentation for oj.ArrayDataGridDataSource for more details on the available options.
  • oj.CollectionDataGridDataSource - Use this when oj.Collection is the model for the underlying data. Note that the DataGrid will automatically react to model event from the underlying oj.Collection. See the documentation for oj.CollectionDataGridDataSource for more details on the available options.
  • oj.CubeDataGridDataSource - Use this when aggregating data with oj.Cube. See the documentation for oj.CubeDataGridDataSource for more details on the available options.
  • oj.PagingDataGridDataSource - Use this when the DataGrid is driven by an associating ojPagingControl. See the documentation for oj.PagingDataGridDataSource for more details on the available options.
  • oj.FlattenedTreeDataGridDataSource - Use this when hierarchical data is displayed in the DataGrid. The FlattenedDataGridDataSource takes an oj.TreeDataSource and adapts that to the DataGridDataSource. The ojRowExpander works with the FlattenedTreeDataGridDataSource to enable expanding/collapsing of rows.

Developers can also create their own DataSource by extending the oj.DataGridDataSource class. See the cookbook for an example of a custom DataGridDataSource.

Touch End User Information

Target Gesture Action
Cell Tap Focus on the cell. If selectionMode for cells is enabled, selects the cell as well. If multiple selection is enabled the selection handles will appear. Tapping a different cell will deselect the previous selection.
Double Tap Enter edit mode if editMode is enabled.
Press & Hold Display context menu
Row Tap If selectionMode for rows is enabled, selects the row as well. If multiple selection is enabled the selection handles will appear. Tapping a different row will deselect the previous selection.
Drag If the row that is dragged contains the active cell and dnd reorder row is enabled the row will be moved within the data grid.
Press & Hold Display context menu
Header Press & Short Hold Focus on the header.
Press & Hold Display context menu
Column Header Tap Sorts the column if sortable enabled.
Header Gridline Drag Resizes the header if resizable enabled along the axis.

Keyboard End User Information

Target Key Action
Cell Tab The first Tab into the DataGrid moves focus to the first cell of the first row. The second Tab moves focus to the next focusable element outside of the DataGrid. If editMode is cellEdit, then it submits the value and moves focus the cell of the next column within the current row. There is no wrapping at the end of the rows.
Shift + Tab The first Shift + Tab into the DataGrid moves focus to the first cell of the first row. The second Shift + Tab moves focus to the previous focusable element outside of the DataGrid. If editMode is cellEdit, then it submits the value and moves focus the cell of the previous column within the current row. There is no wrapping at the beginning of the rows.
Enter If editMode is cellEdit, then it submits the value and moves focus the cell of the next row within the current column. There is no wrapping at the end of the columns.
Shift + Enter If editMode is cellEdit, then it submits the value and moves focus the cell of the previous row within the current column. There is no wrapping at the beginning of the columns.
LeftArrow Moves focus to the cell of the previous column within the current row. There is no wrapping at the beginning or end of the columns. If a row header is present, then the row header next to the first column of the current row will gain focus. Does not change focus if editMode is cellEdit.
RightArrow Moves focus to the cell of the next column within the current row. There is no wrapping at the beginning or end of the columns. Does not change focus if editMode is cellEdit.
UpArrow Moves focus to the cell of the previous row within the current column. There is no wrapping at the beginning or end of the rows. If a column header is present, then the column header above the first row of the current column will gain focus. Does not change focus if editMode is cellEdit.
DownArrow Moves focus to the cell of the next row within the current column. There is no wrapping at the beginning or end of the rows. Does not change focus if editMode is cellEdit.
Home Moves focus to the first (available) cell of the current row. Does not change focus if editMode is cellEdit.
End Moves focus to the last (available) cell of the current row. Does not change focus if editMode is cellEdit.
PageUp Moves focus to the first (available) cell in the current column. Does not change focus if editMode is cellEdit.
PageDown Moves focus to the last (available) cell in the current column. Does not change focus if editMode is cellEdit.
Ctrl + Space Selects all the cells of the current column. This is only available if multiple cell selection mode is enabled.
Shift + Space Selects all the cells of the current row. This is only available if multiple cell selection mode is enabled.
Shift + Arrow Extends the current selection.
Ctrl + Arrow Move focus to level 0 of the active index of the header in the arrow direction if it exists.
Shift + F8 Freezes the current selection, therefore allowing user to move focus to another location to add additional cells to the current selection. This is used to accomplish non-contiguous selection. Use the Esc key or press Shift+F8 again to exit this mode.
Shift + F10 Brings up the context menu.
Ctrl + X Marks the current row to move if dnd is enabled and the datasource supports move operation.
Ctrl + V Move the row that is marked to directly under the current row. If the row with the focused cell is the last row, then it will be move to the row above the current row.
Ctrl + Alt + 5 Read the context and content of the current cell to the screen reader.
F2 If editMode is cellNavigation it switches to cellEdit. If editMode is cellEdit it begins editing the cell keeping the cursor at the end of the input. If the cells are not editable it makes the content of the cell actionable, such as a link.
Alt + Enter If editMode is cellNavigation it switches to cellEdit. If editMode is cellEdit it begins editing the cell keeping the cursor at the end of the input. If the cells are not editable it makes the content of the cell actionable, such as a link.
Esc If editMode is cellEdit it switches to cellNavigation. If the cell is being edited it cancels the edit. If the cell is actionable it exits actionable mode.
Other Keystrokes If editMode is cellEdit it will begin an edit, overwriting the contents of the cell.
Column Header Cell LeftArrow Moves focus to the previous column header. There is no wrapping at the beginning or end of the column headers.
RightArrow Moves focus to the next column header. There is no wrapping at the beginning or end of the column headers.
DownArrow Moves focus to the cell of the first row directly below the column header. If using nested headers will move focus up a level.
UpArrow If using nested headers will move focus down a level.
Ctrl + UpArrow If in the column end header, move focus to level 0 of the active index in the column header if it exists.
Ctrl + DownArrow If in the column header, move focus to level 0 of the active index in the column end header if it exists.
Enter Toggle the sort order of the column if the column is sortable.
Shift + F10 Brings up the context menu.
Row Header Cell UpArrow Moves focus to the previous row header. There is no wrapping at the beginning or end of the row headers.
DownArrow Moves focus to the next row header. There is no wrapping at the beginning or end of the row headers.
RightArrow Moves focus to the cell of the first column directly next to the row header. If using nested headers will move focus up a level.
LeftArrow Moves focus to the cell of the first column directly next to the row header in RTL direction. If using nested headers will move focus down a level.
Ctrl + LeftArrow If in the row end header, move focus to level 0 of the active index in the row header if it exists.
Ctrl + RightArrow If in the row header, move focus to level 0 of the active index in the row end header if it exists.
Shift + F10 Brings up the context menu.

Accessibility

Since role="application" is used in the data grid, application should always apply an aria-label to the data grid element so that it can distinguish from other elements with application role.

Header Context And Cell Context

For all header and cell options, developers can specify a function as the return value. The function takes a single argument, which is an object that contains contextual information about the particular header or cell. This gives developers the flexibility to return different value depending on the context.

For header options, the context paramter contains the following keys:

Key Description
axis The axis of the header. Possible values are 'row', 'column', 'rowEnd', and 'columnEnd'.
component A reference to the DataGrid widgetConstructor.
datasource A reference to the data source object.
index The index of the header, where 0 is the index of the first header.
key The key of the header.
data The data object for the header.
parentElement The header cell element. The renderer can use this to directly append content to the header cell element.
level The level of the header. The outermost header is level zero.
depth The the number of levels the header spans.
extent The number of indexes the header spans.

For cell options, the context paramter contains the following keys:

Key Description
component A reference to the DataGrid widgetConstructor.
datasource A reference to the data source object.
indexes The object that contains both the zero based row index and column index in which the cell is bound to.
keys The object that contains both the row key and column key which identifies the cell.
cell An object containing attribute data which should be used to reference the data in the cell.
data The plain data for the cell.
parentElement The data cell element. The renderer can use this to directly append content to the data cell element.
mode The current mode of the datagrid. Values are navigation and edit.

If a FlattenedTreeDataGridDataSource is used, the following additional contextual information are available:

Key Description
depth The depth of the row. The depth of root row is 0.
index The index of the row relative to its parent. The index of the first child is 0.
state The state of the row. Possible values are "expanded", "collapsed", "leaf".
parentKey The key of the parent row. For root row the parent key is null.

Note that a custom DataGridDataSource can return additional header and cell context information. Consult the documentation of the DataGridDataSource API for details.

Selection

The DataGrid supports both cell based and row based selection mode, which developers can specify using the selectionMode option. For each mode developers can also specify whether single or multiple cells/rows can be selected.

Developers can specify or retrieve selection from the DataGrid using the selection option. A selection in DataGrid consists of an array of ranges. Each range contains the following keys: startIndex, endIndex, startKey, endKey. Each of the keys contains value for 'row' and 'column'. If endIndex and endKey are not specified, that means the range is unbounded, i.e. the cells of the entire row/column are selected.

Geometry Management

If the DataGrid is not styled with a fixed size, then it will responds to a change to the size of its container. Note that unlike Table the content of the cell does not affect the height of the row. The height of the rows must be pre-determined and specified by the developer or a default size will be used.

The DataGrid does not support % width and height values in the header style or style class.

Reading direction

The order of the column headers will be rendered in reverse order in RTL reading direction. The location of the row header will also be different between RTL and LTR direction. It is up to the developers to ensure that the content of the header and data cell are rendered correctly according to the reading direction.

As with any JET component, in the unusual case that the directionality (LTR or RTL) changes post-init, the datagrid must be refresh()ed.

Templating Alignment

When using stamped content through templates, it is no longer required to add the specific class names to achieve proper alignment. The data grid cells are now horizontal flex boxes. To change the alignment use the classes documented in the flex layout section of the cookbook>

Performance

Data Set Size

As a rule of thumb, it's recommended that applications limit the amount of data to display. Displaying large number of items in DataGrid makes it hard for users to find what they are looking for, but affects the scrolling performance as well. If displaying large number of items is neccessary, consider use a paging control with DataGrid to limit the number of items to display at a time. Also consider setting scrollPolicy to 'scroll' to enable virtual scrolling to reduce the number of elements in the DOM at any given time .

Cell Content

DataGrid allows developers to specify arbitrary content inside its cells. In order to minimize any negative effect on performance, you should avoid putting a large number of heavy-weight components inside a cell because as you add more complexity to the structure, the effect will be multiplied because there can be many items in the DataGrid.

Templating

When deciding to use a template or renderer, consider how conditional the template would be. Having templates with several if blocks can significantly hinder performance. If you have this case either specify a function for the template to remove conditions from the template itself or use the renderer option.

Styling

The following CSS classes can be applied by the page author as needed.

Class Description
oj-helper-justify-content-[direction] Use this class on cells' and headers' className property to align your content horizontally. By default the alignment is flex-end on cells and varies on headers, see other possibilities in the flex layout justify section.
oj-helper-align-items-[direction] Use this class on cells' and headers' className prperty to align your content vertically. By default the alignment is center on cells and headers, see other possibilities in the flex layout align section.
oj-datagrid-cell-no-padding Used to style a datagrid cell so that it has no padding. An app developer would likely use this in the case of editable datagrids when an editable cell content does not need the default cell padding.
oj-datagrid-cell-padding Used to style a datagrid cell so that it has the default padding. An app developer would likely use this in the case of editable datagrids when an editable cell content needs to maintain default cell padding.
oj-datagrid-depth-[number] Used to style the default header widths and heights. By default the datagrid supports up to depth 7. If you have headers width depth greater than 7 specify the defaults using the class name description or use apply custom style rules to the headers.

Initializer

.ojDataGrid()

Source:

Options

bandingInterval :Object.<string, number>

Row banding and column banding intervals within the data grid body.
Properties:
Name Type Description
row number row banding interval
column number column banding interval
Default Value:
  • { "row":0, "column":0 }
Source:
Examples

Initialize the data grid with the row banding interval set to every other row:

$( ".selector" ).ojDataGrid({ "data":data, "bandingInterval": {"row":1} });

Get or set the rowBanding option, after initialization:

// get the bandingInterval object
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "bandingInterval" );

// set the bandingInterval to every 2 rows and every other column
$( ".selector" ).ojDataGrid( "option", "bandingInterval", {"row":2, "column":1 } );

cell :Object

The cell option contains a subset of options for databody cells.
Source:

cell.className :function(Object)|string|null

The CSS style class to apply to cells in the data grid body. If a string is specified the class will be added to all cells. A function can be specified with this option. The function would take a single parameter, cellContext, and must return a string to be set as a className. See cellContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with the cell style class set to 'myCellStyle':

$( ".selector" ).ojDataGrid({ "data":data, "cell":{"className":"myCellStyle"} });

Get or set the className option, after initialization:

// get the className string
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "cell.className" );

// set the className string to a function of the cellContext
$( ".selector" ).ojDataGrid( "option", "cell.className", function(cellContext){return cellContext['indexes']['row'] % 2 == 0 ? 'even':'odd'}});

cell.renderer :function(Object)|null

The renderer function that renders the content of the cell. See cellContext in the introduction to see the object passed into the cell renderer function. The function returns either a String or a DOM element of the content inside the data body cell. If the developer chooses to manipulate the cell element directly, the function should return nothing. If no renderer is specified, the Grid will treat the cell data as a String.
Default Value:
  • null
Source:
Examples

Initialize the data grid with cell renderer that capitalizes each character in the cell:

$( ".selector" ).ojDataGrid({ "data":data, "cell": {"renderer": function(cellContext) {
                                           return cellContext['cell']['data'].toUpperCase();}}});

Get or set the renderer option, after initialization:

// get the renderer function
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "cell.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "cell.renderer", myFunction});

cell.style :function(Object)|string|null

The CSS style to apply directly to cells in the data grid body. If a string is specified the style will be added to all cells. A function can be specified with this option. The function would take a single parameter, cellContext, and must return a string. See cellContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with cells to have green backgrounds:

$( ".selector" ).ojDataGrid({ "data":data, "cell":{style: "background-color: green"}});

Initialize the data grid with every other cell to have a green background using a function:

$( ".selector" ).ojDataGrid({ "data":data, "cell": {style: function(cellContext) {
                                           if (cellContext['indexes']['column'] % 2 === 0)
                                              return "background-color: green";
                                           return;}}});

contextMenu :Element|Array.<Element>|string|jQuery|NodeList

Identifies the JET Menu that the component should launch as a context menu on right-click, Shift-F10, Press & Hold, or component-specific gesture. If specified, the browser's native context menu will be replaced by the specified JET Menu.

The value can be an HTML element, JQ selector, JQ object, NodeList, or array of elements. In all cases, the first indicated element is used.

To specify a JET context menu on a DOM element that is not a JET component, see the ojContextMenu binding.

To make the page semantically accurate from the outset, applications are encouraged to specify the context menu via the standard HTML5 syntax shown in the below example. When the component is initialized, the context menu thus specified will be set on the component.

There is no restriction on the order in which the JET Menu and the referencing component are initialized. However, when specifying the Menu via the HTML attribute, the referenced DOM element must be in the document at the time that the referencing component is initialized.

After create time, the contextMenu option should be set via this API, not by setting the DOM attribute.

The application can register a listener for the Menu's beforeOpen event. The listener can cancel the launch via event.preventDefault(), or it can customize the menu contents by editing the menu DOM directly, and then calling refresh() on the Menu.

To help determine whether it's appropriate to cancel the launch or customize the menu, the beforeOpen listener can use component API's to determine which table cell, chart item, etc., is the target of the context menu. See the JSDoc and demos of the individual components for details. Keep in mind that any such logic must work whether the context menu was launched via right-click, Shift-F10, Press & Hold, or component-specific touch gesture.

The DataGrid has a default context menu for accessibly performing operations such as header resize and sort. If no context menu is specified on the data grid, the default value that is set on the contextMenu option is guaranteed to be something accepted by $(). Developers can also specify their own context menu by using the contextMenu option. When defining a context menu, ojDataGrid allows the app to use the built-in behavior for operations such as header resize and sort by specifying menu list items as follows.

  • <li data-oj-command="oj-datagrid-['commandname']" />

Note that if no <a> element is specified inside of a list item with a command, the translated text from the default menu will be supplied in an anchor tag.

The supported commands:

Default Function data-oj-command value
Resize menu (contains width and height resize) oj-datagrid-resize
Sort Row menu (contains ascending and descending sort) oj-datagrid-sortRow
Sort Column menu (contains ascending and descending sort) oj-datagrid-sortCol
Resize Width oj-datagrid-resizeWidth
Resize Height oj-datagrid-resizeHeight
Sort Row Ascending oj-datagrid-sortRowAsc
Sort Row Descending oj-datagrid-sortRowDsc
Sort Column Ascending oj-datagrid-sortColAsc
Sort Column Descending oj-datagrid-sortColDsc
Cut oj-datagrid-cut
Paste oj-datagrid-paste
Toggle Non-Contiguous Selection on Touch Device oj-datagrid-discontiguousSelection
Default Value:
  • null|Element
Source:
Examples

Initialize a JET component with a context menu:

// via recommended HTML5 syntax:
<div id="myComponent" contextmenu="myMenu" data-bind="ojComponent: { ... }>

// via JET initializer (less preferred) :
// Foo is the component, e.g., InputText, InputNumber, Select, etc.
$( ".selector" ).ojFoo({ "contextMenu": "#myMenu" });

Get or set the contextMenu option, after initialization:

// getter
// Foo is the component, e.g., InputText, InputNumber, Select, etc.
var menu = $( ".selector" ).ojFoo( "option", "contextMenu" );

// setter
// Foo is the component, e.g., InputText, InputNumber, Select, etc.
$( ".selector" ).ojFoo( "option", "contextMenu", ".my-marker-class" );

Set a JET context menu on an ordinary HTML element:

<a href="#" id="myAnchor" contextmenu="myMenu" data-bind="ojContextMenu: {}">Some text

currentCell :Object

The current databody or header cell. This is typically the item the user navigated to. Note that if currentCell is set to an item that is currently not available (not fetched in highwatermark scrolling case or inside a collapsed parent node) or invalid, then the value is ignored. If the currentCell is a databody cell the object will contain the following information: {type: 'cell', indexes: {row:0, column:0}, keys: {row:'Apple', column:'Sales'}}. If the currentCell is a header cell the object will contain the following information: {type: 'header', axis:'column', index: 0, key: 'Apple', level:0}. If setting the option to a databody cell, either indexes or keys must be specified, if both are specified indexes will be used as a hint. If setting the option to a header cell, axis and either "index and level" or "key" must be specified, if both are specified "index and level" will be used as a hint. If level is not specified it will default to 0.
Default Value:
  • null
Source:
Examples

Get the current cell:

$( ".selector" ).ojDataGrid("option", "currentCell");

Set the current databody cell based on index on the DataGrid during initialization:

$(".selector").ojDataGrid({"currentCell", {indexes: {row:0, column:0}}});

Set the current header cell based on index and level on the DataGrid during initialization:

$(".selector").ojDataGrid({"currentCell", {axis:'column', index:0, level:0);

Set the current databody cell based on keys on the DataGrid during initialization:

$(".selector").ojDataGrid({"currentCell", {keys: {row:'Apple', column:'Sales'}}});

Set the current header cell based on keys on the DataGrid during initialization:

$(".selector").ojDataGrid({"currentCell", {axis:'column', key: 'Apple'}});

data :oj.DataGridDataSource

The data source for the DataGrid must be an extension of oj.DataGridDataSource. See the data source section in the introduction for out of the box data source types. To specify a row header key or index of an ArrayDataGridDataSource pass in an Object as such: {"data": oj.DataGridDataSource, "rowHeader":string|number} If the data attribute is not specified, an empty data grid is displayed.
Default Value:
  • null
Source:
Examples

Initialize the data grid with a one-dimensional array:

$( ".selector" ).ojDataGrid({ "data": new oj.ArrayDataGridDataSource([1,2,3])});

Initialize the data grid with a two-dimensional array:

$( ".selector" ).ojDataGrid({ "data": new oj.ArrayDataGridDataSource(['X','X','O'],['O','X','O'],['O','O','X'])});

Initialize the data grid with a two-dimensional array and set an index for row headers:

$( ".selector" ).ojDataGrid({ "data":{"rowHeader":2 , "data": new oj.ArrayDataGridDataSource(['1','2','Cat'],['1','4','Dog'],['5','1','Bird']) }});

Initialize the data grid with an oj.Collection:

$( ".selector" ).ojDataGrid({ "data": new oj.CollectionDataGridDataSource(collection)});

Initialize the data grid with an oj.Collection and specify a row header:

$( ".selector" ).ojDataGrid({ "data":{ "data":new oj.CollectionDataGridDataSource(collection), "rowHeader":'key' }});

Initialize the data grid with a custom data source

$( ".selector" ).ojDataGrid({ "data":new CustomDataSource()});

dnd :Object

Enables or disables reordering the rows within the same datagrid using drag and drop.

Specify an object with the property "reorder" set to {'row':'enable'} to enable reordering. Setting the "reorder" property to {'row':'disable'}, or setting the "dnd" property to null (or omitting it), disables reordering support. There must be move capability on the datasource to support this feature.
Properties:
Name Type Description
reorder Object an object with property row
Properties
Name Type Description
row string row reordering within the datagrid: "enable", "disable"
Default Value:
  • {reorder: {row :'disable'}}
Source:
Example

Initialize the data grid to enable single row reorder:

$( ".selector" ).ojDataGrid({ "data":data, "dnd" : {"reorder":{"row":"enable"}}});

editMode :string

Determine if the grid is read only or editable. Use 'none' if the grid is strictly read only. Use 'cellNavigation' if you want editable cells, but the grid is currently read only and a single tab stop on the page. Pressing F2 or double click while in this mode will switch to 'cellEdit' mode. Use 'cellEdit' if you want editable cells, and tab navigates to the next cell behavior. Pressing ESC while in this mode will switch to 'cellNavigation' mode.
Supported Values:
Name Type Description
"none" string the grid is read only
"cellNavigation" string the grid is a single tab stop and editable at the cell level, but currently read only
"cellEdit" string the grid cells are indivdually tabbable and editable
Default Value:
  • "none"
Source:
Example

Initialize the data grid with cell editing enabled:

$( ".selector" ).ojDataGrid({ "data":data, "editMode": "cell"});

gridlines :Object.<string, string>

Display or hide the horizontal or vertical grid lines in the data body. Gridlines are visible by default, and must be set to 'hidden' in order to be hidden.
Properties:
Name Type Description
horizontal string horizontal gridlines, valid values are: "hidden", "visible"
vertical string vertical gridlines, valid values are: "hidden", "visible"
Default Value:
  • {"horizontal": "visible", "vertical": "visible"}
Source:
Example

Initialize the data grid with only horizontal gridlines visible:

$( ".selector" ).ojDataGrid({ "data":data, "gridlines": {"horizontal": "visible", "vertical": "hidden"} });
The header option contains a subset of options for row and column headers.
Source:

header.column

The header column option contains a subset of options for column headers.
Source:

header.column.className :function(Object)|string|null

The CSS style class to apply to column headers in the data grid. If a string is specified the class will be added to all column header cells. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string to be set as a className. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with column header style calss set to 'chstyle':

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {"className":"chstyle"} } });

Get or set the className option, after initialization:

// get the className string
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.column.className" );

// set the className string to a function of the headerContext
$( ".selector" ).ojDataGrid( "option", "header.column.className", function(headerContext){return headerContext['index'] % 2 == 0 ? 'even':'odd'}});

header.column.renderer :function(Object)|null

The renderer function that renders the content of the column header. See headerContext in the introduction to see the object passed into the column header renderer function. The function returns either a String or a DOM element of the content inside the column header. If the developer chooses to manipulate the column header element directly, the function should return nothing. If no renderer is specified, the Grid will treat the header data as a String.
Default Value:
  • null
Source:
Examples

Initialize the data grid with column header renderer that capitalizes each character in the column header cells:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {"renderer": function(headerContext) {
                                           return headerContext['key'].toUpperCase();}}}});

Get or set the renderer option, after initialization:

// get the renderer function
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.column.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "header.column.renderer", myFunction});

header.column.resizable :Object.<string, string>|Object.<string, function(Object)>|null

Enable or disable width or height resize along the column headers. Note that for column header, a function cannot be used with "height". A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string of enable or disable. See headerContext for details.
Properties:
Name Type Description
width string column width resizable valid values are: "enable", "disable"
height string column header height resizable valid values are: "enable", "disable"
Default Value:
  • {"width": "disable", "height": "disable"}
Source:
Examples

Initialize the data grid with column header width resizable only:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {"resizable": {"width":"enable"}}}});

Initialize the data grid with every other column header width resizable:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {"resizable": {"width":function(headerContext){ return headerContext['index'] % 2 === 0 ? 'enable':'disable'; }}}}});

header.column.sortable :function(Object)|string

Enable or disable sorting on the field bounded by this header. The data source associated with the DataGrid must have the sort function defined. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string of auto, enable, or disable. See headerContext for details.
Supported Values:
Name Type Description
"auto" string get the sortable property from the data source
"enable" string enable sorting on column headers
"disable" string disable sorting on column headers
Default Value:
  • "auto"
Source:
Examples

Initialize the data grid with column header sort disabled:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {"sortable": "disable"}}});

Initialize the data grid with every other column header sort enabled:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {"sortable": function(headerContext){ return headerContext['index'] % 2 === 0 ? 'auto':'disable'; }}}});

header.column.style :function(Object)|string|null

The inline style to apply to column headers in the data grid. If a string is specified the class will be added to all column header cells. Note that % width/height value is not supported. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with column headers to have green backgrounds:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {style: "background-color: green"}}});

Initialize the data grid with every other column header to have a green background:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "column": {style: function(headerContext) {
                                           if (headerContext['index'] % 2 === 0)
                                              return "background-color: green";
                                           return;}}}});

header.columnEnd

The header columnEnd option contains a subset of options for column end headers.
Source:

header.columnEnd.className :function(Object)|string|null

The CSS style class to apply to column end headers in the data grid. If a string is specified the class will be added to all column end header cells. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string to be set as a className. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with column end header style calss set to 'chstyle':

$( ".selector" ).ojDataGrid({ "data":data, "header": { "columnEnd": {"className":"chstyle"} } });

Get or set the className option, after initialization:

// get the className string
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.columnEnd.className" );

// set the className string to a function of the headerContext
$( ".selector" ).ojDataGrid( "option", "header.columnEnd.className", function(headerContext){return headerContext['index'] % 2 == 0 ? 'even':'odd'}});

header.columnEnd.renderer :function(Object)|null

The renderer function that renders the content of the column end header. See headerContext in the introduction to see the object passed into the column end header renderer function. The function returns either a String or a DOM element of the content inside the column end header. If the developer chooses to manipulate the column end header element directly, the function should return nothing. If no renderer is specified, the Grid will treat the header data as a String.
Default Value:
  • null
Source:
Examples

Initialize the data grid with column end header renderer that capitalizes each character in the column end header cells:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "columnEnd": {"renderer": function(headerContext) {
                                           return headerContext['key'].toUpperCase();}}}});

Get or set the renderer option, after initialization:

// get the renderer function
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.columnEnd.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "header.columnEnd.renderer", myFunction});

header.columnEnd.resizable :Object.<string, string>|Object.<string, function(Object)>|null

Enable or disable width or height resize along the column end headers. Note that for column end header, a function cannot be used with "height". A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string of enable or disable. See headerContext for details.
Properties:
Name Type Description
width string column end header width resizable valid values are: "enable", "disable"
height string column end header height resizable valid values are: "enable", "disable"
Default Value:
  • {"width": "disable", "height": "disable"}
Source:
Examples

Initialize the data grid with column end header width resizable only:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "columnEnd": {"resizable": {"width":"enable"}}}});

Initialize the data grid with every other column end header width resizable:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "columnEnd": {"resizable": {"width":function(headerContext){ return headerContext['index'] % 2 === 0 ? 'enable':'disable'; }}}}});

header.columnEnd.style :function(Object)|string|null

The inline style to apply to column end headers in the data grid. If a string is specified the class will be added to all column end header cells. Note that % width/height value is not supported. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with column end headers to have green backgrounds:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "columnEnd": {style: "background-color: green"}}});

Initialize the data grid with every other columnEnd header to have a green background:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "columnEnd": {style: function(headerContext) {
                                           if (headerContext['index'] % 2 === 0)
                                              return "background-color: green";
                                           return;}}}});

header.row

The header row option contains a subset of options for row headers.
Source:

header.row.className :function(Object)|string|null

The CSS style class to apply to row headers in the data grid. If a string is specified the class will be added to all row header cells. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string to be set as a className. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with row header style calss set to 'rhstyle':

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {"className":"rhstyle"} } });

Get or set the className option, after initialization:

// get the className string
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.row.className" );

// set the className string to a function of the headerContext
$( ".selector" ).ojDataGrid( "option", "header.row.className", function(headerContext){return headerContext['index'] % 2 == 0 ? 'even':'odd'}});

header.row.renderer :function(Object)|null

The renderer function that renders the content of the row header. See headerContext in the introduction to see the object passed into the row header renderer function. The function returns either a String or a DOM element of the content inside the row header. If the developer chooses to manipulate the row header element directly, the function should return nothing. If no renderer is specified, the Grid will treat the header data as a String.
Default Value:
  • null
Source:
Examples

Initialize the data grid with row header renderer that capitalizes each character in the row header cells:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {"renderer": function(headerContext) {
                                           return headerContext['key'].toUpperCase();}}}});

Get or set the renderer option, after initialization:

// get the renderer function
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.row.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "header.row.renderer", myFunction});

header.row.resizable :Object.<string, string>|Object.<string, function(Object)>|null

Enable or disable width or height resize along the row headers. Note that for row header, a function cannot be used with "width". A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string of enable or disable. See headerContext for details.
Properties:
Name Type Description
width string row width resizable valid values are: "enable", "disable"
height string row header height resizable valid values are: "enable", "disable"
Default Value:
  • {"width": "disable", "height": "disable"}
Source:
Examples

Initialize the data grid with row header height resizable only:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {"resizable": {"height":"enable"}}}});

Initialize the data grid with every other row header height resizable:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {"resizable": {"height":function(headerContext){ return headerContext['index'] % 2 === 0 ? 'enable':'disable'; }}}}});

header.row.sortable :function(Object)|string

Enable or disable sorting on the field bounded by this header. The data source associated with the DataGrid must have the sort function defined. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string of auto, enable, or disable. See headerContext for details.
Supported Values:
Name Type Description
"auto" string get the sortable property from the data source
"enable" string enable sorting on row headers
"disable" string disable sorting on row headers
Default Value:
  • "auto"
Source:
Examples

Initialize the data grid with row header sort disabled:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {"sortable": "disable"}}});

Initialize the data grid with every other row header sort enabled:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {"sortable": function(headerContext){ return headerContext['index'] % 2 === 0 ? 'auto':'disable'; }}}});

header.row.style :function(Object)|string|null

The inline style to apply to row headers in the data grid. If a string is specified the class will be added to all row header cells. Note that % width/height value is not supported. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with row headers to have green backgrounds:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {style: "background-color: green"}}});

Initialize the data grid with every other row header to have a green background:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "row": {style: function(headerContext) {
                                           if (headerContext['index'] % 2 === 0)
                                              return "background-color: green";
                                           return;}}}});

header.rowEnd

The header rowEnd option contains a subset of options for row end headers.
Source:

header.rowEnd.className :function(Object)|string|null

The CSS style class to apply to row end headers in the data grid. If a string is specified the class will be added to all row end header cells. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string to be set as a className. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with row end header style calss set to 'chstyle':

$( ".selector" ).ojDataGrid({ "data":data, "header": { "rowEnd": {"className":"chstyle"} } });

Get or set the className option, after initialization:

// get the className string
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.rowEnd.className" );

// set the className string to a function of the headerContext
$( ".selector" ).ojDataGrid( "option", "header.rowEnd.className", function(headerContext){return headerContext['index'] % 2 == 0 ? 'even':'odd'}});

header.rowEnd.renderer :function(Object)|null

The renderer function that renders the content of the row end header. See headerContext in the introduction to see the object passed into the row end header renderer function. The function returns either a String or a DOM element of the content inside the row end header. If the developer chooses to manipulate the row end header element directly, the function should return nothing. If no renderer is specified, the Grid will treat the header data as a String.
Default Value:
  • null
Source:
Examples

Initialize the data grid with row end header renderer that capitalizes each character in the row end header cells:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "rowEnd": {"renderer": function(headerContext) {
                                           return headerContext['key'].toUpperCase();}}}});

Get or set the renderer option, after initialization:

// get the renderer function
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "header.rowEnd.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "header.rowEnd.renderer", myFunction});

header.rowEnd.resizable :Object.<string, string>|Object.<string, function(Object)>|null

Enable or disable width or height resize along the row end headers. Note that for row end header, a function cannot be used with "width". A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string of enable or disable. See headerContext for details.
Properties:
Name Type Description
width string row end header width resizable valid values are: "enable", "disable"
height string row end header height resizable valid values are: "enable", "disable"
Default Value:
  • {"width": "disable", "height": "disable"}
Source:
Examples

Initialize the data grid with row end header height resizable only:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "rowEnd": {"resizable": {"height":"enable"}}}});

Initialize the data grid with every other row end header height resizable:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "rowEnd": {"resizable": {"height":function(headerContext){ return headerContext['index'] % 2 === 0 ? 'enable':'disable'; }}}}});

header.rowEnd.style :function(Object)|string|null

The inline style to apply to row end headers in the data grid. If a string is specified the class will be added to all row end header cells. Note that % width/height value is not supported. A function can be specified with this option. The function would take a single parameter, headerContext, and must return a string. See headerContext for details.
Default Value:
  • null
Source:
Examples

Initialize the data grid with row end headers to have green backgrounds:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "rowEnd": {style: "background-color: green"}}});

Initialize the data grid with every other rowEnd header to have a green background:

$( ".selector" ).ojDataGrid({ "data":data, "header": { "rowEnd": {style: function(headerContext) {
                                           if (headerContext['index'] % 2 === 0)
                                              return "background-color: green";
                                           return;}}}});

rootAttributes :Object

Attributes specified here will be set on the component's root DOM element at creation time. This is particularly useful for components like Dialog that wrap themselves in a new root element at creation time.

The supported attributes are id, which overwrites any existing value, and class and style, which are appended to the current class and style, if any.

Setting this option after component creation has no effect. At that time, the root element already exists, and can be accessed directly via the widget method, per the second example below.

Default Value:
  • null
Inherited From:
Source:
Examples

Initialize a JET component, specifying a set of attributes to be set on the component's root DOM element:

// Foo is the component, e.g., Menu, Button, InputText, InputNumber, Select, etc.
$( ".selector" ).ojFoo({ "rootAttributes": {
  "id": "myId",
  "style": "max-width:100%; color:blue;",
  "class": "my-class"
}});

After initialization, rootAttributes should not be used. It is not needed at that time, as attributes of the root DOM element can simply be set directly, using widget:

// Foo is the component, e.g., Menu, Button, InputText, InputNumber, Select, etc.
$( ".selector" ).ojFoo( "widget" ).css( "height", "100px" );
$( ".selector" ).ojFoo( "widget" ).addClass( "my-class" );

scrollPolicy :string|null

Specifies the mechanism used to scroll the data inside the data grid. possible values are: auto(datagrid will decide), loadMoreOnScroll, and scroll. When loadMoreOnScroll is specified, additional data are fetched when the user scrolls to the bottom of the data grid. When scroll is specified, then virtual scrolling is used meaning only rows/columns visibile in the viewport are fetched.
Default Value:
  • null
Source:
Example

Initialize the data grid to use virtualized scrolling:

$( ".selector" ).ojDataGrid({ "data":data, "scrollPolicy": "scroll"});

scrollPosition :Object.<string, Object>|null

The index or key of the row and/or column to display initially in the data grid. Only key or index should be specified, if they both are the grid will scroll initially to the key values.
Properties:
Name Type Description
index Object scroll to a given row and column index of the datagrid
Properties
Name Type Description
row number row index to scroll to
column number column index to scroll to
key Object scroll to a given row and column key of the datagrid
Properties
Name Type Description
row string row key to scroll to
column string column key to scroll to
Default Value:
  • null
Source:
Examples

Initialize the data grid to scroll to row index 5 and column index 7:

$( ".selector" ).ojDataGrid({ "data":data, "scrollPosition": {"index":{"row": 5, "column": 7}}});

Initialize the data grid to scroll to row key 'id5' and column key 'id7':

$( ".selector" ).ojDataGrid({ "data":data, "scrollPosition": {"key":{"row": "id5", "column": "id7"}}});

selection :Array.<Object>

Specifies the current selections in the data grid. Returns an array of range objects, or an empty array if there's no selection.
Default Value:
  • []
Source:
Examples

Get the current selection:

$( ".selector" ).ojDataGrid("option", "selection");

Set a row selection on the grid during initialization:

$(".selector").ojDataGrid({"selection", [{startIndex: {"row":1}, endIndex:{"row":3}}]});

Set a cell selection on the grid during initialization:

$(".selector").ojDataGrid({"selection", [{startIndex: {"row":1, "column":2}, endIndex: {"row":3, "column":4}}]});

Set a row selection on the grid after initialization:

$(".selector").ojDataGrid("option", "selection", [{startIndex: {"row":1}, endIndex:{"row":3}}]);

Set a cell selection on the grid after initialization:

$(".selector").ojDataGrid("option", "selection", [{startIndex: {"row":1, "column":2}, endIndex: {"row":3, "column":4}}]);

selectionMode :Object.<string, string>|null

Specifies whether row/cell selection can be made and the cardinality of each (single/multiple/none) selection in the Grid. Only one of the properties, row or column, should be set at at time. Selection is initially disabled, but setting the value to null will disable selection.
Properties:
Name Type Description
row string set row selection mode, valid values are: "single", "multiple"
cell string set cell selection mode, valid values are: "single", "multiple"
Default Value:
  • null
Source:
Examples

Initialize the data grid to enable single row selection:

$( ".selector" ).ojDataGrid({ "data":data, "selectionMode": {"row":"single"}});

Initialize the data grid to enable multiple cell selection:

$( ".selector" ).ojDataGrid({ "data":data, "selectionMode": {"cell":"multiple"}});

translations :Object

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If this component has (or inherits) translations, their documentation immediately follows this doc entry.

Default Value:
  • an object containing all resources relevant to the component and all its superclasses, or null if none
Inherited From:
Source:
Examples

Initialize the component, overriding some translated resources. This syntax leaves the other translations intact at create time, but not if called after create time:

// Foo is InputDate, InputNumber, etc.
$( ".selector" ).ojFoo({ "translations": { someKey: "someValue",
                                           someOtherKey: "someOtherValue" } });

Get or set the translations option, after initialization:

// Get one.  (Foo is InputDate, InputNumber, etc.)
var value = $( ".selector" ).ojFoo( "option", "translations.someResourceKey" );

// Get all.  (Foo is InputDate, InputNumber, etc.)
var values = $( ".selector" ).ojFoo( "option", "translations" );

// Set one, leaving the others intact.  (Foo is InputDate, InputNumber, etc.)
$( ".selector" ).ojFoo( "option", "translations.someResourceKey", "someValue" );

// Set many.  Any existing resource keys not listed are lost.  (Foo is InputDate, InputNumber, etc.)
$( ".selector" ).ojFoo( "option", "translations", { someKey: "someValue",
                                                    someOtherKey: "someOtherValue" } );

translations.accessibleActionableMode :Object

Provides properties to customize the accesible context to enter actionable mode.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleColumnContext :Object

Provides properties to customize the accesible context for the column index.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleColumnEndHeaderContext :Object

Provides properties to customize the accesible context for the column end header index.

See the translations option for usage examples.

Since:
  • 2.1.0
Source:

translations.accessibleColumnHeaderContext :Object

Provides properties to customize the accesible context for the column header index.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleColumnSelected :Object

Provides properties to customize the accesible context when a column is selected.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleEditableMode :Object

Provides properties to customize the accesible context to enter editable mode.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleFirstColumn :Object

Provides properties to customize the accesible context when the first column is reached.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleFirstRow :Object

Provides properties to customize the accesible context when the first row is reached.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleLastColumn :Object

Provides properties to customize the accesible context when the last column is reached.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleLastRow :Object

Provides properties to customize the accesible context when the last row is reached.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleLevelContext :Object

Provides properties to customize the accesible context for the header level.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleMultiCellSelected :Object

Provides properties to customize the accesible context when mulitple cells are selected.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleNavigationMode :Object

Provides properties to customize the accesible context to enter navigation mode.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRangeSelectModeOff :Object

Provides properties to customize the accesible context for discontinuous selection off.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRangeSelectModeOn :Object

Provides properties to customize the accesible context for discontinuous selection on.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRowCollapsed :Object

Provides properties to customize the accesible context when a row is collapsed.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRowContext :Object

Provides properties to customize the accesible context for the row index.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRowEndHeaderContext :Object

Provides properties to customize the accesible context for the row end header index.

See the translations option for usage examples.

Since:
  • 2.1.0
Source:

translations.accessibleRowExpanded :Object

Provides properties to customize the accesible context when a row is expanded.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRowHeaderContext :Object

Provides properties to customize the accesible context for the row header index.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleRowSelected :Object

Provides properties to customize the accesible context when a row is selected.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSelectionAffordanceBottom :Object

Provides properties to customize the accesible context for the bottom selection affordance on touch device.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSelectionAffordanceTop :Object

Provides properties to customize the accesible context for the top selection affordance on touch devices.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSortAscending :Object

Provides properties to customize the accesible text when a header is sorted ascending.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSortDescending :Object

Provides properties to customize the accesible text when a header is sorted descending.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleStateSelected :Object

Provides properties to customize the accesible context when an item has been selected.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSummaryEstimate :Object

Provides properties to customize the accesible context read when the exact row and column count are unknown.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSummaryExact :Object

Provides properties to customize the accesible context read when the exact row and column count are known.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.accessibleSummaryExpanded :Object

Provides properties to customize the accesible context reading out the total number of rows expanded inside the data grid.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelCut :Object

Provides properties to customize the context menu cut label for row reordering.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelDisableNonContiguous :Object

Provides properties to customize the context menu label for exiting non-contigous selection.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelEnableNonContiguous :Object

Provides properties to customize the context menu label for entering non-contigous selection.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelPaste :Object

Provides properties to customize the context menu paste label for row reordering.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelResize :Object

Provides properties to customize the context menu resize label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelResizeDialogSubmit :Object

Provides properties to customize the resize dialog submit button.

See the translations option for usage examples.

Since:
  • 1.2.0
Source:

translations.labelResizeHeight :Object

Provides properties to customize the context menu resize height label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelResizeWidth :Object

Provides properties to customize the context menu resize width label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelSortCol :Object

Provides properties to customize the context menu sort column label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelSortColAsc :Object

Provides properties to customize the context menu sort column ascending label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelSortColDsc :Object

Provides properties to customize the context menu sort column descending label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelSortRow :Object

Provides properties to customize the context menu sort row label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelSortRowAsc :Object

Provides properties to customize the context menu sort row ascending label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.labelSortRowDsc :Object

Provides properties to customize the context menu sort row descending label.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.msgFetchingData :Object

Provides properties to customize the text when fetching data.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

translations.msgNoData :Object

Provides properties to customize the empty data grid text.

See the translations option for usage examples.

Since:
  • 1.1.0
Source:

Binding Attributes

Binding attributes are similar to component options, but are exposed only via the ojComponent binding.

cell.template :function(Object)|string|null

The knockout template used to render the content of the cell. This attribute is only exposed via the ojComponent binding, and is not a component option.
Default Value:
  • null
Source:
Examples

Specify the cell template when initializing DataGrid:

$( ".selector" ).ojDataGrid({ "data":data, "cell": {"template": 'my_template' }});

Initialize the data grid with a edit and a navigation template:

$( ".selector" ).ojDataGrid({ "data":data, "cell": {"template": function(cellContext){return (cellContext['mode'] === 'edit') ? 'editTemplate' : 'navigationTemplate';} }});

header.column.template :string|null

The knockout template used to render the content of the column header. This attribute is only exposed via the ojComponent binding, and is not a component option.
Default Value:
  • null
Source:
Example

Specify the column header template when initializing DataGrid:

// set the template
<ul id="datagrid" data-bind="ojComponent: {component: 'ojDataGrid', data: dataSource, header: { column: {template: 'my_template'}}}"></ul>

header.columnEnd.template :string|null

The knockout template used to render the content of the column end header. This attribute is only exposed via the ojComponent binding, and is not a component option.
Default Value:
  • null
Source:
Example

Specify the column end header template when initializing DataGrid:

// set the template
<ul id="datagrid" data-bind="ojComponent: {component: 'ojDataGrid', data: dataSource, header: { columnEnd: {template: 'my_template'}}}"></ul>

header.row.template :string|null

The knockout template used to render the content of the row header. This attribute is only exposed via the ojComponent binding, and is not a component option.
Default Value:
  • null
Source:
Example

Specify the row header template when initializing DataGrid:

// set the template
<ul id="datagrid" data-bind="ojComponent: {component: 'ojDataGrid', data: dataSource, header: { row: {template: 'my_template'}}}"></ul>

header.rowEnd.template :string|null

The knockout template used to render the content of the row end header. This attribute is only exposed via the ojComponent binding, and is not a component option.
Default Value:
  • null
Source:
Example

Specify the row end header template when initializing DataGrid:

// set the template
<ul id="datagrid" data-bind="ojComponent: {component: 'ojDataGrid', data: dataSource, header: { rowEnd: {template: 'my_template'}}}"></ul>

Context Objects

Each context object contains, at minimum, a subId property, whose value is a string that identifies a particular DOM node in this component. It can have additional properties to further specify the desired node. See getContextByNode for more details.

Properties:
Name Type Description
subId string Sub-id string to identify a particular dom node.

Following are the valid subIds:

oj-datagrid-cell

Context for the ojDataGrid component's cells.

Properties:
Name Type Description
component function a reference to the DataGrid widgetConstructor
data Object the data object for the header
datasource Object a reference to the data source object
indexes Object the object that contains both the zero based row index and column index in which the cell is bound to
Properties
Name Type Description
row number the zero based absolute row index
column number the zero based absolute column index
keys Object the object that contains both the row key and column key which identifies the cell
Properties
Name Type Description
row number | string the row key
column number | string the column key
mode string the mode the cell is rendered in
Source:

oj-datagrid-header

Context for the ojDataGrid component's headers.

Properties:
Name Type Description
axis number the axis of the header, possible values are 'row'/'column'/'columnEnd'/'rowEnd'
component function a reference to the DataGrid widgetConstructor
data Object the data object for the header
datasource Object a reference to the data source object
depth number the the number of levels the header spans
extent number the number of indexes the header spans
index number the index of the header, where 0 is the index of the first header
key number | string the key of the header
level number the level of the header. The outermost header is level zero
Source:

Sub-ID's

Each subId locator object contains, at minimum, a subId property, whose value is a string that identifies a particular DOM node in this component. It can have additional properties to further specify the desired node. See getNodeBySubId and getSubIdByNode methods for more details.

Properties:
Name Type Description
subId string Sub-id string to identify a particular dom node.

Following are the valid subIds:

oj-datagrid-cell

Sub-ID for the ojDataGrid component's cells.

To lookup a cell the locator object should have the following:
  • subId: 'oj-datagrid-cell'
  • rowIndex: the zero based absolute row index
  • columnIndex: the zero based absolute column index
Source:
Example

Get the cell at row index 1 and column index 2:

var node = $( ".selector" ).ojDataGrid( "getNodeBySubId", {'subId': 'oj-datagrid-cell', 'rowIndex': 1, 'columnIndex': 2} );

oj-datagrid-header

Sub-ID for the ojDataGrid component's headers.

To lookup a header the locator object should have the following:
  • subId: 'oj-datagrid-header'
  • axis: 'column'/'row'/'columnEnd'/'rowEnd'
  • index: the zero based absolute row/column index.
  • level: the zero based header level, 0 is the outer edge, if not specified will default to 0
Source:
Example

Get the header at the specified location:

var node = $( ".selector" ).ojDataGrid( "getNodeBySubId", {'subId': 'oj-datagrid-header', 'axis': 'column', 'index':0, 'level':0} );

oj-datagrid-sort-ascending

Sub-ID for the ojDataGrid component's sort ascending icon in column headers.

To lookup a sort icon the locator object should have the following:
  • subId: 'oj-datagrid-sort-ascending'
  • axis: 'column'
  • index: the zero based absolute column index
  • level: the zero based header level, 0 is the outer edge, if not specified will default to 0
Source:
Example

Get the sort icon from the header at the specified location:

var node = $( ".selector" ).ojDataGrid( "getNodeBySubId", {'subId': 'oj-datagrid-sort-ascending', 'axis': 'column', 'index':0, 'level':0} );

oj-datagrid-sort-descending

Sub-ID for the ojDataGrid component's sort descending icon in column headers.

To lookup a sort icon the locator object should have the following:
  • subId: 'oj-datagrid-sort-descending'
  • axis: 'column'
  • index: the zero based absolute column index
  • level: the zero based header level, 0 is the outer edge, if not specified will default to 0
Source:
Example

Get the descending sort icon from the header at the specified location:

var node = $( ".selector" ).ojDataGrid( "getNodeBySubId", {'subId': 'oj-datagrid-sort-descending', 'axis': 'column', 'index':0, 'level':0} );

oj-datagrid-sort-icon

Deprecated:
Source:

Events

#beforeCurrentCell

Triggered before the current cell is changed via the currentCell option or via the UI.
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
currentCell Object the new current cell, see currentCell for the object information
previousCurrentCell Object the previous current cell, see currentCell for the object information
Source:
Examples

Initialize the ojDataGrid with the beforeCurrentCell callback specified:

$( ".selector" ).ojDataGrid({
    "beforeCurrentCell": function( event, ui ) {}
});

Bind an event listener to the ojbeforecurrentcell event:

$( ".selector" ).on( "ojbeforecurrentcell", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

#beforeEdit

Triggered before the data grid is going to enter edit mode. To prevent editing the cell return false.
Properties:
Name Type Description
event Event jQuery event object that caused the edit
ui Object Parameters
Properties
Name Type Description
cellContext Object the cellContext of the cell that editing is going to be performed on
Source:
Examples

Initialize the data grid with the beforeEdit callback specified:

$( ".selector" ).ojDataGrid({
    "beforeEdit": function( event, ui ) {}
});

Bind an event listener to the ojbeforeedit event:

$( ".selector" ).on( "ojbeforeedit", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

#beforeEditEnd

Triggered before the data grid is going to exit edit mode. To prevent exit editing the return false. There is a provided beforeEditEnd function, oj.DataCollectionEditUtils.basicHandleEditEnd, which can be specified. This function will handle canceling edits as well as invoking validation on input components.
Properties:
Name Type Description
event Event jQuery event object that caused the edit
ui Object Parameters
Properties
Name Type Description
cellContext Object the cellContext of the cell that editing is going to be performed on
cancelEdit boolean true if the edit should be negated based on actions (i.e. escape key)
Source:
Examples

Initialize the data grid with the beforeEditEnd callback specified:

$( ".selector" ).ojDataGrid({
    "beforeEditEnd": function( event, ui ) {}
});

Bind an event listener to the ojbeforeeditend event:

$( ".selector" ).on( "ojbeforeeditend", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

destroy

Triggered before the component is destroyed. This event cannot be canceled; the component will always be destroyed regardless.

Inherited From:
Source:
Examples

Initialize component with the destroy callback

// Foo is Button, InputText, etc.
$(".selector").ojFoo({
  'destroy': function (event, data) {}
});

Bind an event listener to the destroy event

$(".selector").on({
  'ojdestroy': function (event, data) {
      // verify that the component firing the event is a component of interest
      if ($(event.target).is(".mySelector")) {
          window.console.log("The DOM node id for the destroyed component is : %s", event.target.id);
      }
  };
});

optionChange

Fired whenever a supported component option changes, whether due to user interaction or programmatic intervention. If the new value is the same as the previous value, no event will be fired. The event listener will receive two parameters described below:
Properties:
Name Type Description
event Event jQuery event object
ui Object event payload
Properties
Name Type Argument Description
option string the name of the option that changed.
previousValue Object an Object holding the previous value of the option. When previousValue is not a primitive type, i.e., is an Object, it may hold the same value as the value property.
value Object an Object holding the current value of the option.
subproperty Object <nullable>
an Object holding information about the subproperty that changed.
Properties
Name Type Description
path string the subproperty path that changed.
previousValue Object an Object holding the previous value of the subproperty.
value Object an Object holding the current value of the subproperty.
optionMetadata Object information about the option that changed
Properties
Name Type Description
writeback string "shouldWrite" or "shouldNotWrite". For use by the JET writeback mechanism; 'shouldWrite' indicates that the value should be written to the observable.
Inherited From:
Source:
Examples

Initialize component with the optionChange callback

// Foo is Button, InputText, etc.
$(".selector").ojFoo({
  'optionChange': function (event, ui) {}
});

Bind an event listener to the ojoptionchange event

$(".selector").on({
  'ojoptionchange': function (event, ui) {
      // verify that the component firing the event is a component of interest
      if ($(event.target).is(".mySelector")) {
          window.console.log("option that changed is: " + ui['option']);
      }
  };
});

#ready

Triggered after all items in the DataGrid has been rendered. Note that in the highwatermark or virtual scrolling case this means all items means the items that are fetched so far.
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Deprecated:
Source:
Examples

Initialize the DataGrid with the ready callback specified:

$( ".selector" ).ojDataGrid({
    "ready": function( event, ui ) {}
});

Bind an event listener to the ojready event:

$( ".selector" ).on( "ojready", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

#resize

Triggered when a portion of the data grid is resized
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
header string | number the key of the header which was resized
size string DEPRECATED, please use the ui.oldDimensions and ui.newDimensions properties
oldDimensions Object
Properties
Name Type Description
width number the old pixel size (ex: '75px' would be 75)
height number the old pixel size
newDimensions Object
Properties
Name Type Description
width number the new pixel size (ex: '75px' would be 75)
height number the new pixel size
Source:
Examples

Initialize the data grid with the resize callback specified:

$( ".selector" ).ojDataGrid({
    "resize": function( event, ui ) {}
});

Bind an event listener to the ojresize event:

$( ".selector" ).on( "ojresize", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

#scroll

Triggered after the data grid has been scrolled via the UI or the scrollTo method.
Properties:
Name Type Description
event Event event object that caused the scroll
ui Object Parameters
Properties
Name Type Description
scrollX number the x position in pixels of the scrollable region calculated from the origin of the datagrid. In RTL this would be the right of the grid.
scrollY number the y position in pixels of the scrollable region
Source:
Examples

Initialize the DataGrid with the scroll callback specified:

$( ".selector" ).ojDataGrid({ "scroll": function( event, ui ) {} }); 

Bind an event listener to the ojscroll event:

$( ".selector" ).on( "ojscroll", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

#sort

Triggered when a sort is performed on the data grid
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
header Element the key of the header which was sorted on
direction string the direction of the sort ascending/descending
Source:
Examples

Initialize the data grid with the sort callback specified:

$( ".selector" ).ojDataGrid({
    "sort": function( event, ui ) {}
});

Bind an event listener to the ojsort event:

$( ".selector" ).on( "ojsort", function( event, ui ) {
     // verify that the component firing the event is a component of interest 
     if ($(event.target).is(".mySelector"))
});

Methods

getContextByNode(node) → {Object|null}

Returns an object with context for the given child DOM node. This will always contain the subid for the node, defined as the 'subId' property on the context object. Additional component specific information may also be included. For more details on returned objects, see context objects.
Parameters:
Name Type Description
node Element The child DOM node
Source:
Returns:
- The context for the DOM node, or null when none is found.
Type
Object | null
Example
  
// Foo is ojInputNumber, ojInputDate, etc.
// Returns {'subId': oj-foo-subid, 'property1': componentSpecificProperty, ...}
var context = $( ".selector" ).ojFoo( "getContextByNode", nodeInsideComponent );

#getNodeBySubId(locator) → {Array.<(Element|null)>|Element|null}

Return the subcomponent node represented by the documented locator attribute values.

To lookup a cell the locator object should have the following:

  • subId: 'oj-datagrid-cell'
  • rowIndex: the zero based absolute row index
  • columnIndex: the zero based absolute column index
To lookup a header the locator object should have the following:
  • subId: 'oj-datagrid-header'
  • axis: 'column'/'row'/'columnEnd'/'rowEnd'
  • index: the zero based absolute row/column index.
  • level: the zero based header level, 0 is the outer edge, if not specified will default to 0
For nested headers the index increments by the extent of the header. So if the header at index 0 on a level has an extent of 4, the next header on that level will be at index 4. To lookup a sort icon the locator object should have the following:
  • subId: 'oj-datagrid-sort-ascending'/'oj-datagrid-sort-descending'
  • axis: 'column'/'row'
  • index: the zero based absolute row/column index
  • level: the zero based header level, 0 is the outer edge, if not specified will default to 0
Parameters:
Name Type Description
locator Object An Object containing at minimum a subId property whose value is a string, documented by the component, that allows the component to look up the subcomponent associated with that string. It contains:

component: optional - in the future there may be more than one component contained within a page element

subId: the string, documented by the component, that the component expects in getNodeBySubId to locate a particular subcomponent

Source:
Returns:
the subcomponent located by the subId string passed in locator, if found.

Type
Array.<(Element | null)> | Element | null

getSubIdByNode(node) → {Object|null}

Returns the subId string for the given child DOM node. For more details, see getNodeBySubId.
Parameters:
Name Type Description
node Element child DOM node
Source:
Returns:
The subId for the DOM node, or null when none is found.
Type
Object | null
Example

Get the subId for a certain DOM node:

var subId = $( ".selector" ).ojDataGrid( "getSubIdByNode", nodeInsideComponent );

option(optionName, value) → {Object|undefined}

This method has several overloads, which get and set component options and their fields. The functionality is unchanged from that provided by JQUI. See the examples for details on each overload.

Parameters:
Name Type Argument Description
optionName string | Object <optional>
the option name (string, first two overloads), or the map (Object, last overload). Omitted in the third overload.
value Object <optional>
a value to set for the option. Second overload only.
Inherited From:
Source:
Returns:
The getter overloads return the retrieved value(s). When called via the public jQuery syntax, the setter overloads return the object on which they were called, to facilitate method chaining.
Type
Object | undefined
Examples

First overload: get one option:

This overload accepts a (possibly dot-separated) optionName param as a string, and returns the current value of that option.

var isDisabled = $( ".selector" ).ojFoo( "option", "disabled" ); // Foo is Button, Menu, etc.

// For object-valued options, dot notation can be used to get the value of a field or nested field.
var startIcon = $( ".selector" ).ojButton( "option", "icons.start" ); // icons is object with "start" field

Second overload: set one option:

This overload accepts two params: a (possibly dot-separated) optionName string, and a new value to which that option will be set.

$( ".selector" ).ojFoo( "option", "disabled", true ); // Foo is Button, Menu, etc.

// For object-valued options, dot notation can be used to set the value
// of a field or nested field, without altering the rest of the object.
$( ".selector" ).ojButton( "option", "icons.start", myStartIcon ); // icons is object with "start" field

Third overload: get all options:

This overload accepts no params, and returns a map of key/value pairs representing all the component options and their values.

var options = $( ".selector" ).ojFoo( "option" ); // Foo is Button, Menu, etc.

Fourth overload: set one or more options:

This overload accepts a single map of option-value pairs to set on the component. Unlike the first two overloads, dot notation cannot be used.

$( ".selector" ).ojFoo( "option", { disabled: true, bar: 42 } ); // Foo is Button, Menu, etc.

#refresh()

Redraw the entire data grid after having made some external modifications.

This method does not accept any arguments.

Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the refresh method:

$( ".selector" ).ojDataGrid( "refresh" );

#scrollTo(options)

Scroll the datagrid to an x,y pixel location. If the x,y point is outside the range of the viewport the grid will scroll to the nearest location. If high-watermark scrolling is used, the grid will scroll within the currently fetched range.
Parameters:
Name Type Description
options Object an object containing the scrollTo information
Properties
Name Type Description
position Object scroll to an x,y pixel location which is relative to the origin of the grid
Properties
Name Type Description
scrollX Object the x position in pixels of the scrollable region relative to the origin of the grid, this should always be positive. If RTL the value is the scroll position from the right of the grid.
scrollY Object the Y position in pixels of the scrollable region, this should always be positive.
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the scrollTo method:

$(".selector").ojDataGrid("scrollTo", {"position": {"scrollX": 50, "scrollY":100}});

whenReady() → {Promise}

Returns a Promise that resolves when the component is ready, i.e. after data fetching, rendering, and animations complete. Note that in the highwatermark scrolling case, component is ready after data fetching, rendering, and associated animations of items fetched so far are complete.

This method does not accept any arguments.

Source:
Returns:
A Promise that resolves when the component is ready.
Type
Promise

Non-public Methods

Note: Extending JET components is not currently supported. Thus, non-public methods are for internal use only.

<protected, static> _AfterCreate()

Initialize the grid after creation
Source:

<protected, static> _ComponentCreate()

Create the grid
Source:

<protected> _AddActiveable(options)

Add touch and mouse listeners to toggle oj-active class
Parameters:
Name Type Description
options !Object | !jQuery This parameter can either be the element (convenience syntax for callers needing to specify only the element(s) that would otherwise have been passed as options.element) or an object supporting the following fields:
Properties
Name Type Argument Description
element jQuery The element(s) to receive the oj-active class on active Required if afterToggle is specified.
afterToggle function(string) <nullable>
Optional callback function called each time the active classes have been toggled, after the toggle. The event.type string is passed and indicates whether the classes were added or removed. The active classes are added on "touchstart" or "mousedown" or "mouseenter" and the active classes are removed on "touchend" or "touchcancel" or "mouseup" or "mouseleave". Components with consistency requirements, such as "oj-default must be applied iff no state classes such as oj-active are applied," can enforce those rules in this callback.
Inherited From:
Source:
See:

<protected> _AddHoverable(options)

Add mouse listners to toggle oj-hover class
Parameters:
Name Type Description
options !Object | !jQuery This param can either be the element (convenience syntax for callers needing to specify only the element(s) that would otherwise have been passed as options.element) or an object supporting the following fields:
Properties
Name Type Argument Description
element jQuery The element(s) to receive the oj-hover class on hover Required if afterToggle is specified.
afterToggle function(string) <nullable>
Optional callback function called each time the hover classes have been toggled, after the toggle. The string "mouseenter" or "mouseleave" is passed, indicating whether the classes were added or removed. Components with consistency requirements, such as "oj-default must be applied iff no state classes such as oj-hover are applied," can enforce those rules in this callback.
Inherited From:
Source:
See:

<protected> _AfterCreate()

This method is called after _ComponentCreate, but before the create event is fired. The JET base component does tasks here that must happen after the component (subclass) has created itself in its override of _ComponentCreate. Notably, the base component handles the rootAttributes and contextMenu options here, since those options operate on the component root node, which for some components is created in their override of _ComponentCreate.

Subclasses should override this method only if they have tasks that must happen after a superclass's implementation of this method, e.g. tasks that must happen after the context menu is set on the component.

Overrides of this method should call this._super first.

Inherited From:
Source:

<protected> _AfterCreateEvent()

This method is called after the create event is fired. Components usually should not override this method, as it is rarely correct to wait until after the create event to perform a create-time task.

An example of a correct usage of this method is Dialog's auto-open behavior, which needs to happen after the create event.

Only behaviors (like Dialog auto-open behavior) should occur in this method. Component initialization must occur earlier, before the create event is fired, so that create listeners see a fully inited component.

Overrides of this method should call this._super first.

Do not confuse this method with the _AfterCreate method, which is more commonly used.

Inherited From:
Source:

<protected> _CompareOptionValues(option, value1, value2) → {boolean}

Compares 2 option values for equality and returns true if they are equal; false otherwise.

Parameters:
Name Type Description
option String the name of the option
value1 Object first value
value2 Object another value
Inherited From:
Source:
Returns:
Type
boolean

<protected> _ComponentCreate()

All component create-time initialization lives in this method, except the logic that specifically needs to live in _InitOptions, _AfterCreate, or _AfterCreateEvent, per the documentation for those methods. All DOM creation must happen here, since the intent of _AfterCreate, which is called next, is to contain superclass logic that must run after that DOM is created.

Overrides of this method should call this._super first.

Summary of create-time methods that components can override, in the order that they are called:

  1. _InitOptions
  2. _ComponentCreate (this method)
  3. _AfterCreate
  4. (The create event is fired here.)
  5. _AfterCreateEvent

For all of these methods, the contract is that overrides must call this._super first, so e.g., the _ComponentCreate entry means baseComponent._ComponentCreate, then _ComponentCreate in any intermediate subclasses, then _ComponentCreate in the leaf subclass.

Inherited From:
Source:

<protected> _create()

This method is final in JET. Components should instead override one or more of the overridable create-time methods listed in _ComponentCreate.

Inherited From:
Source:

<protected> _FixRendererContext(context) → {Object}

Prepares a custom renderer context object for either the JQuery or custom element syntax, removing and exposing keys as needed.
Parameters:
Name Type Description
context Object The renderer context object.
Inherited From:
Source:
Returns:
The cleaned up renderer context.
Type
Object

<protected> _focusable(options)

Sets JET's "focus" CSS classes when the element is focused and removes them when focus is lost.

The oj-focus class is set on all focuses.

Some components additionally have an oj-focus-highlight class, which applies a focus indicator that is appropriate on a subset of the occasions that oj-focus is appropriate. Those components should pass true for the applyHighlight param, in which case the oj-focus-highlight class is set if appropriate given the current focus highlight policy.

Focus highlight policy

The focus highlight policy supports the 3 values listed below. By default, it is retrieved from the $focusHighlightPolicy SASS variable, shared by many components and patterns. Components with different needs, including those exposing a component-specific SASS variable or other API for this, should see the getFocusHighlightPolicy parameter below. Valid focus highlight policies:

Policy Description
"nonPointer" Indicates that the component should apply the oj-focus-highlight class only for focuses not resulting from pointer (touch or mouse) interaction. (In the built-in themes, the SASS variable defaults to this value.)
"all" Indicates that the component should apply the class for all focuses.
"none" Indicates that the component should never apply the class, because the application has taken responsibility for applying the class when needed for accessibility.
Toggling the classes

Components that toggle these focus classes outside of this API must maintain the invariant that oj-focus-highlight is applied to a given element in a (not necessarily strict) subset of cases that oj-focus is applied to that element.

Typically the specified element should be within the component subtree, in which case the classes will automatically be removed from the element when the component is destroyed, when its disabled option is set to true, and when _NotifyDetached() is called.

As a minor exception, for components that wrap themselves in a new root node at create time, if the specified element is within the root node's subtree but not within the init node's subtree, then at destroy time only, the classes will not be removed, since destroy() is expected to remove such nodes.

If the element is NOT in the component subtree, then the caller is responsible for removing the classes at the times listed above.

Listeners

If setupHandlers is not passed, or if setupHandlers is passed and uses _on to register its listeners as seen in the example, then the listeners are not invoked when the component is disabled, and the listeners are automatically cleaned up when the component is destroyed. Otherwise, the caller is responsible for ensuring that the disabled state is handled correctly, and removing the listeners at destroy time.

Related API's

Non-component internal callers should see oj.DomUtils.makeFocusable(). Per its JSDoc (unpublished; see the source), it has a couple of additional usage considerations.

Parameters:
Name Type Description
options !Object | !jQuery This param can either be the element (convenience syntax for callers needing to specify only the element(s) that would otherwise have been passed as options.element) or an object supporting the following fields:
Properties
Name Type Argument Description
element jQuery The element(s) to receive the oj-focus classes on focus. Required if setupHandlers not passed; ignored otherwise.
applyHighlight boolean true if the oj-focus-highlight class should be applied when appropriate. false or omitted if that class should never be applied.
afterToggle function(string) <nullable>
Optional callback function called each time the focus classes have been toggled, after the toggle. The string "focusin" or "focusout" is passed, indicating whether the classes were added or removed. Components with consistency requirements, such as "oj-default must be applied iff no state classes such as oj-focus are applied," can enforce those rules in this callback.
getFocusHighlightPolicy function() <nullable>
Optional if applyHighlight is true; ignored otherwise. Components with a component-specific focus policy mechanism should pass a function that always returns one of the three valid values listed above, keeping in mind that this method can be called on every focus. See the example.
recentPointer function() <nullable>
Relevant iff applyHighlight is true and the focus highlight policy is "nonPointer"; ignored otherwise. Recent pointer activity is considered to have occurred if (a) a mouse button or finger has recently been down or up, or (b) this optional callback function returns true. Components wishing to additionally take into account (say) recent pointer movements can supply a function returning true if those movements have been detected, keeping in mind that this method can be called on every focus. See the example.
setupHandlers function(function(!jQuery),function(!jQuery)) <nullable>
Can be omitted by components whose focus classes need to be added and removed on focusin and focusout, respectively. Components needing to add/remove those classes in response to other events should specify this parameter, which is called once, immediately. See the examples.
Inherited From:
Source:
Examples

Opt into the highlight behavior, and specify a function to be called every time the classes are toggled:

var self = this;
this._focusable({
    'element': this.element, 
    'applyHighlight': true, 
    'afterToggle' : function() {
        self._toggleDefaultClasses();
    }
});

Arrange for mouse movement to be considered in addition to mouse/finger up/down. Also supply a component-specific focusHighlightPolicy:

var self = this;
this._focusable({
    'element': someElement, 
    'applyHighlight': true, 
    'recentPointer' : function() {
        // A timestamp-based approach avoids the risk of getting stuck in an inaccessible 
        // state if (say) mouseenter is not followed by mouseleave for some reason.
        var millisSincePointerMove = Date.now() - _myPointerMoveTimestamp;
        var isRecent = millisSincePointerMove < myThreshold;
        return isRecent;
    },
    'getFocusHighlightPolicy' : function() {
        // Return the value of a component-specific SASS $variable, component option, or other 
        // component-specific mechanism, either "all", "none", or "nonPointer".  SASS variables
        // should be pulled into JS once statically on load, not per-instance or per-focus.
    }
});

Add/remove the focus classes in response to events other than focusin/focusout:

var self = this;
this._focusable({
    'applyHighlight': myBooleanValue, 
    'setupHandlers': function( focusInHandler, focusOutHandler) {
        self._on( self.element, {
            // This example uses focus/blur listeners, which don't bubble, rather than the 
            // default focusin/focusout (which bubble).  This is useful when one focusable  
            // element is a descendant of another.
            focus: function( event ) {
                focusInHandler($( event.currentTarget ));
            },
            blur: function( event ) {
                focusOutHandler($( event.currentTarget ));
            }
        });
    }
});

Alternate usage of setupHandlers, which simply stashes the handlers so they can be called from the component's existing handlers:

var self = this;
this._focusable({
    'applyHighlight': myBooleanValue, 
    'setupHandlers': function( focusInHandler, focusOutHandler) {
        self._focusInHandler = focusInHandler;
        self._focusOutHandler = focusOutHandler;
    }
});

<protected> _getCreateOptions()

This method is not used in JET. Components should instead override _InitOptions.

Inherited From:
Source:

<protected> _GetEventForSyntax(event) → {Object}

Given an event, returns the appropriate event for the component syntax. For custom elements, if the event is a JQuery event, this method will return the unwrapped original event.
Parameters:
Name Type Description
event Object [description]
Inherited From:
Source:
Returns:
Type
Object

<protected> _GetReadingDirection() → {string}

Determines whether the component is LTR or RTL.

Component responsibilities:

  • All components must determine directionality exclusively by calling this protected superclass method. (So that any future updates to the logic can be made in this one place.)
  • Components that need to know the directionality must call this method at create-time and from refresh(), and cache the value.
  • Components should not call this at other times, and should instead use the cached value. (This avoids constant DOM queries, and avoids any future issues with component reparenting (i.e. popups) if support for directional islands is added.)

App responsibilities:

  • The app specifies directionality by setting the HTML "dir" attribute on the <html> node. When omitted, the default is "ltr". (Per-component directionality / directional islands are not currently supported due to inadequate CSS support.)
  • As with any DOM change, the app must refresh() the component if the directionality changes dynamically. (This provides a hook for component housekeeping, and allows caching.)
Default Value:
  • "ltr"
Inherited From:
Source:
Returns:
the reading direction, either "ltr" or "rtl"
Type
string

<protected> _GetSavedAttributes(element) → {Object|null}

Gets the saved attributes for the provided element.

If you don't override _SaveAttributes and _RestoreAttributes, then this will return null.

If you override _SaveAttributes to call _SaveAllAttributes, then this will return all the attributes. If you override _SaveAttributes/_RestoreAttributes to do your own thing, then you may also have to override _GetSavedAttributes to return whatever you saved if you need access to the saved attributes.

Parameters:
Name Type Description
element Object jQuery selection, should be a single entry
Inherited From:
Source:
Returns:
savedAttributes - attributes that were saved for this element in _SaveAttributes, or null if none were saved.
Type
Object | null

<protected> _init()

JET components should almost never implement this JQUI method. Please consult an architect if you believe you have an exception. Reasons:

  • This method is called at create time, after the create event is fired. It is rare for that to be the appropriate time to perform a create-time task. For those rare cases, we have the _AfterCreateEvent method, which is preferred over this method since it is called only at that time, not also at re-init time (see next).
  • This method is also called at "re-init" time, i.e. when the initializer is called after the component has already been created. JET has not yet identified any desired semantics for re-initing a component.
Inherited From:
Source:

<protected> _InitOptions(originalDefaults, constructorOptions)

This method is called before _ComponentCreate, at which point the component has not yet been rendered. Component options should be initialized in this method, so that their final values are in place when _ComponentCreate is called.

This includes getting option values from the DOM, where applicable, and coercing option values (however derived) to their appropriate data type if needed.

No work other than setting options should be done in this method. In particular, nothing should be set on the DOM until _ComponentCreate, e.g. setting the disabled DOM attribute from the disabled option.

A given option (like disabled) appears in the constructorOptions param iff the app set it in the constructor:

  • If it appears in constructorOptions, it should win over what's in the DOM (e.g. disabled DOM attribute). If for some reason you need to tweak the value that the app set, then enable writeback when doing so: this.option('foo', bar, {'_context': {writeback: true, internalSet: true}}).
  • If it doesn't appear in constructorOptions, then that option definitely is not bound, so writeback is not needed. So if you need to set the option (e.g. from a DOM attribute), use this.option('foo', bar, {'_context': {internalSet: true}}).

Overrides of this method should call this._super first.

Parameters:
Name Type Argument Description
originalDefaults Object original default options defined on the component and its ancestors
constructorOptions Object <nullable>
options passed into the widget constructor
Inherited From:
Source:

<protected> _IsCustomElement() → {boolean}

Determines whether the component is being rendered as a custom element.
Inherited From:
Source:
Returns:
True if the component is being rendered as a custom element
Type
boolean

<protected> _IsEffectivelyDisabled() → {boolean}

Determines whether this component is effectively disabled, i.e. it has its 'disabled' attribute set to true or it has been disabled by its ancestor component.

Inherited From:
Source:
Returns:
true if the component has been effectively disabled, false otherwise
Type
boolean

<protected> _NotifyAttached()

Notifies the component that its subtree has been connected to the document programmatically after the component has been created.

Inherited From:
Source:

<protected> _NotifyContextMenuGesture(menu, event, eventType)

When the contextMenu option is set, this method is called when the user invokes the context menu via the default gestures: right-click, Press & Hold, and Shift-F10. Components should not call this method directly.

The default implementation simply calls this._OpenContextMenu(event, eventType). Overrides of this method should call that same method, perhaps with additional params, not menu.open().

This method may be overridden by components needing to do things like the following:

  • Customize the launcher or position passed to _OpenContextMenu(). See that method for guidance on these customizations.
  • Customize the menu contents. E.g. some components need to enable/disable built-in commands like Cut and Paste, based on state at launch time.
  • Bail out in some cases. E.g. components with UX approval to use PressHoldRelease rather than Press & Hold can override this method to say if (eventType !== "touch") this._OpenContextMenu(event, eventType);. When those components detect the alternate context menu gesture (e.g. PressHoldRelease), that separate listener should call this._OpenContextMenu(), not this method (_NotifyContextMenuGesture()), and not menu.open().

Components needing to do per-launch setup like the above tasks should do so in an override of this method, not in a beforeOpen listener or an _OpenContextMenu() override. This is discussed more fully here.

Parameters:
Name Type Description
menu Object The JET Menu to open as a context menu. Always non-null.
event Event What triggered the menu launch. Always non-null.
eventType string "mouse", "touch", or "keyboard". Never null.
Inherited From:
Source:

<protected> _NotifyDetached()

Notifies the component that its subtree has been removed from the document programmatically after the component has been created.

Inherited From:
Source:

<protected> _NotifyDetached()

Notifies the component that its subtree has been removed from the document programmatically after the component has been created.

Inherited From:
Source:

<protected> _NotifyHidden()

Notifies the component that its subtree has been made hidden programmatically after the component has been created.

Inherited From:
Source:

<protected> _NotifyShown()

Notifies the component that its subtree has been made visible programmatically after the component has been created.

Inherited From:
Source:

<protected> _OpenContextMenu(event, eventType, openOptions, submenuOpenOptions, shallow)

The only correct way for a component to open its context menu is by calling this method, not by calling Menu.open() or _NotifyContextMenuGesture(). This method should be called in two cases:

  • This method is called by _NotifyContextMenuGesture() and its overrides. That method is called when the baseComponent detects the default context menu gestures: right-click, Press & Hold, and Shift-F10.
  • Components with UX-approved support for alternate context menu gestures like PressHoldRelease should call this method directly when those gestures are detected.

Components needing to customize how the context menu is launched, or do any per-launch setup, should do so in the caller of this method, (which is one of the two callers listed above), often by customizing the params passed to this method (_OpenContextMenu) per the guidance below. This setup should not be done in the following ways:

  • Components should not perform setup in a beforeOpen listener, as this can cause a race condition where behavior depends on who got their listener registered first: the component or the app. The only correct component use of a beforeOpen listener is when there's a need to detect whether something else launched the menu.
  • Components should not override this method (_OpenContextMenu), as this method is final. Instead, customize the params that are passed to it.

Guidance on setting OpenOptions fields:

Launcher:

Depending on individual component needs, any focusable element within the component can be the appropriate launcher for this launch.

Browser focus returns to the launcher on menu dismissal, so the launcher must at least be focusable. Typically a tabbable (not just focusable) element is safer, since it just focuses something the user could have focused on their own.

By default (i.e. if openOptions is not passed, or if it lacks a launcher field), the component init node is used as the launcher for this launch. If that is not focusable or is suboptimal for a given component, that component should pass something else. E.g. components with a "roving tabstop" (like Toolbar) should typically choose the current tabstop as their launcher.

The :focusable and :tabbable selectors may come in handy for choosing a launcher, e.g. something like this.widget().find(".my-class:tabbable").first().

Position:

By default, this method applies positioning that differs from Menu's default in the following ways: (The specific settings are subject to change.)

  • For mouse and touch events, the menu is positioned relative to the event, not the launcher.
  • For touch events, "my" is set to "start>40 center", to avoid having the context menu obscured by the user's finger.

Usually, if position needs to be customized at all, the only thing that needs changing is its "of" field, and only for keyboard launches (since mouse/touch launches should almost certainly keep the default "event" positioning). This situation arises anytime the element relative to which the menu should be positioned for keyboard launches is different than the launcher element (the element to which focus should be returned upon dismissal). For this case, { "position": {"of": eventType==="keyboard" ? someElement : "event"} } can be passed as the openOptions param.

Be careful not to clobber useful defaults by specifying too much. E.g. if you only want to customize "of", don't pass other fields like "my", since your value will be used for all modalities (mouse, touch, keyboard), replacing the modality-specific defaults that are usually correct. Likewise, don't forget the eventType==="keyboard" check if you only want to customize "of" for keyboard launches.

InitialFocus:

This method forces initialFocus to "menu" for this launch, so the caller needn't specify it.

Parameters:
Name Type Argument Description
event Event What triggered the context menu launch. Must be non-null.
eventType string "mouse", "touch", or "keyboard". Must be non-null. Passed explicitly since caller knows what it's listening for, and since events like contextmenu and click can be generated by various input modalities, making it potentially error-prone for this method to determine how they were generated.
openOptions Object <optional>
Options to merge with this method's defaults, which are discussed above. The result will be passed to Menu.open(). May be null or omitted. See also the shallow param.
submenuOpenOptions Object <optional>
Options to be passed through to Menu.open(). May be null or omitted.
shallow boolean <optional>
Whether to perform a deep or shallow merge of openOptions with this method's default value. The default and most commonly correct / useful value is false.
  • If true, a shallow merge is performed, meaning that the caller's position object, if passed, will completely replace this method's default position object.
  • If false or omitted, a deep merge is performed. For example, if the caller wishes to tweak position.of while keeping this method's defaults for position.my, position.at, etc., it can pass {"of": anOfValue} as the position value.

The shallow param is n/a for submenuOpenOptions, since this method doesn't apply any defaults to that. (It's a direct pass-through.)

Inherited From:
Source:

<protected> _ReleaseResources()

Release resources held by this component, for example, remove listeners. This is called during destroy. _SetupResources will set up resources needed by this component, and is called during _create.

This base class default implementation does nothing.

Component subclasses can opt in by overriding _SetupResources and _ReleaseResources.
Inherited From:
Source:

<protected> _RemoveActiveable(element)

Remove touch and mouse listeners that were registered in _AddActiveable
Parameters:
Name Type Description
element jQuery The same element passed to _AddActiveable
Inherited From:
Source:
See:

<protected> _RemoveHoverable(element)

Remove mouse listners that were registered in _AddHoverable
Parameters:
Name Type Description
element jQuery The same element passed to _AddHoverable
Inherited From:
Source:
See:

<protected> _RestoreAllAttributes()

Restores all the element's attributes which were saved in _SaveAllAttributes. This method is final in JET.

If a subclass wants to save/restore all attributes on create/destroy, then the subclass can override _SaveAttributes and call _SaveAllAttributes and also override _RestoreAttributes and call _RestoreAllAttributes.

Inherited From:
Source:

<protected> _RestoreAttributes()

Restore the attributes saved in _SaveAttributes.

_SaveAttributes is called during _create. And _RestoreAttributes is called during _destroy.

This base class default implementation does nothing.

We also have _SaveAllAttributes and _RestoreAllAttributes methods that save and restore all the attributes on an element. Component subclasses can opt into these _SaveAllAttributes/_RestoreAllAttributes implementations by overriding _SaveAttributes and _RestoreAttributes to call _SaveAllAttributes/_RestoreAllAttributes. If the subclass wants a different implementation (like save only the 'class' attribute), it can provide the implementation itself in _SaveAttributes/_GetSavedAttributes/_RestoreAttributes.

Inherited From:
Source:

<protected> _SaveAllAttributes(element)

Saves all the element's attributes within an internal variable. _RestoreAllAttributes will restore the attributes from this internal variable.

This method is final in JET. Subclasses can override _RestoreAttributes and call _RestoreAllAttributes.

The JSON variable will be held as:

[
  {
  "element" : element[i],
  "attributes" :
    {
      attributes[m]["name"] : {"attr": attributes[m]["value"]
    }
  }
]
Parameters:
Name Type Description
element Object jQuery selection to save attributes for
Inherited From:
Source:

<protected> _SaveAttributes(element)

Saves the element's attributes. This is called during _create. _RestoreAttributes will restore all these attributes and is called during _destroy.

This base class default implementation does nothing.

We also have _SaveAllAttributes and _RestoreAllAttributes methods that save and restore all the attributes on an element. Component subclasses can opt into these _SaveAllAttributes/_RestoreAllAttributes implementations by overriding _SaveAttributes and _RestoreAttributes to call _SaveAllAttributes/_RestoreAllAttributes. If the subclass wants a different implementation (like save only the 'class' attribute), it can provide the implementation itself in _SaveAttributes/_RestoreAttributes.

Parameters:
Name Type Description
element Object jQuery selection to save attributes for
Inherited From:
Source:

<protected> _SetRootAttributes()

Reads the rootAttributes option, and sets the root attributes on the component's root DOM element. See rootAttributes for the set of supported attributes and how they are handled.

Inherited From:
Source:
Throws:
if unsupported attributes are supplied.

<protected> _SetupResources()

Sets up needed resources for this component, for example, add listeners. This is called during _create. _ReleaseResources will release resources help by this component, and is called during destroy.

This base class default implementation does nothing.

Component subclasses can opt in by overriding _SetupResources and _ReleaseResources.
Inherited From:
Source:

<protected> _UnregisterChildNode()

Remove all listener references that were attached to the element.
Inherited From:
Source: