Class: ojDataGrid

Oracle® JavaScript Extension Toolkit (JET)
2.0.0

E70325-01

QuickNav

Options


Binding Attributes
Context Objects
Sub-ID's

oj. ojDataGrid extends oj.baseComponent

Version:
  • 2.0.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.
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.
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.
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.
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.
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.
Home Moves focus to the first (available) cell of the current row.
End Moves focus to the last (available) cell of the current row.
PageUp Moves focus to the first (available) cell in the current column.
PageDown Moves focus to the last (available) cell in the current column.
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.
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.
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.
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.
LeftArrow Moves focus to the cell of the first column directly next to the row header in RTL direction.
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' and 'column'.
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.
data The data object for the cell.
parentElement The data cell element. The renderer can use this to directly append content to the data cell element.

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.

The DataGrid has a default context menu for operations such as header resize and sort. Developers can also specify their own context menu by using the contextMenu option.

When defining a contextMenu, ojDataGrid will provide built-in behavior for "edit" style functionality (e.g. cut/copy/paste) if the following format for menu <li> item's is used (no <a> elements are required):

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

The available translated text will be applied to menu items defined this way.

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

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 required to add specific class name's to obtain the default cell content alignment. In the case of header templates, add the class name oj-datagrid-header-cell-text. In the cell template case add the class name oj-datagrid-cell-text to obtain default cell alignment. These classes styles and default behavior are themable.

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.

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['index'] % 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['key'].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['index'] % 2 === 0)
                                              return "background-color: green";
                                           return;}}});

contextMenu :Object

JQ selector identifying 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.

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.

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

Default Value:
  • null
Inherited From:
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"}}});

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 row 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", "column.header.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "column.header.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.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", "row.header.renderer" );

// set the renderer function
$( ".selector" ).ojDataGrid( "option", "row.header.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 "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 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;}}}});

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.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.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.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 :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:
Example

Specify the cell template when initializing DataGrid:

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

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.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>

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
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' and 'column'
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'
  • 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 ) {} );

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) {
      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. Currently there is one supported option, "selection". Additional options may be supported in the future, so listeners should verify which option is changing before taking any action.
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
option string the name of the option that is changing
previousValue Object the previous value of the option
value Object the current value of the option
optionMetadata Object information about the option that is changing
Properties
Name Type Description
writeback string "shouldWrite" or "shouldNotWrite". For use by the JET writeback mechanism.
Source:

#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 ) {} );

#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 ) {} );

#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 ) {} );

#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 ) {} );

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'
  • 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> _activeable(element)

Sets the oj-active class on mousedown and removes it on mouseup. oj-active is one of JET's 'marker' style classes. It emulates the css :active pseudo-class.

Unlike _hoverable() and _focusable(), this is an original JET method not inherited from JQUI. (Obviously inspired by those methods.)

Typically the specified element should be within the component subtree, in which case the class 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 class 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 class at the times listed above.

Parameters:
Name Type Description
element jQuery The element to receive the oj-active class when pressed
Inherited From:
Source:

<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> _focusable(element)

Sets the oj-focus class when the element is focused and removes it when focus is lost.

Overridden to set the oj-focus class instead of JQUI's hard-coded ui- class, and eliminate JQUI's caching.

Typically the specified element should be within the component subtree, in which case the class 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 class 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 class at the times listed above.

Parameters:
Name Type Description
element jQuery The element to receive the oj-focus class on focus
Inherited From:
Source:

<protected> _getCreateOptions()

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

Inherited From:
Source:

<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> _hoverable(element)

Sets the oj-hover class when the element is hovered and removes it when the hover ends.

Overridden to set the oj-hover class instead of JQUI's hard-coded ui- class, and eliminate JQUI's caching.

Typically the specified element should be within the component subtree, in which case the class 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 class 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 class at the times listed above.

Parameters:
Name Type Description
element jQuery The element to receive the oj-hover class on hover
Inherited From:
Source:

<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> _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> _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> _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"], "prop": $(element[i]).prop(attributes[m]["name"])
    }
  }
]
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> _UnregisterChildNode()

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