Class: ojDataGrid

Oracle® Fusion Middleware Oracle JavaScript Extension Toolkit (JET)
12c (12.1.4)

E54107-01

QuickNav

oj. ojDataGrid extends oj.baseComponent

Initializer

.ojDataGrid()

Source:

Options

#bandingInterval :Object.<string, number>

Banding interval for rows/columns within the data grid body.
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:

// getter
var bandingInterval = $( ".selector" ).ojDataGrid( "option", "bandingInterval" );

// setter
$( ".selector" ).ojDataGrid( "option", "bandingInterval", {"row":1, "column":1 } );

#className :string|null

A CSS style class to use for the row header.
Default Value:
  • null
Source:
Example

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

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

#className :string|null

A CSS style class to use for the column header.
Default Value:
  • null
Source:
Example

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

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

#className :string|null

A CSS style class to use for the cell.
Default Value:
  • null
Source:
Example

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

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

#contextMenu :Object

JQ selector identifying the JET Menu that the component should launch as a context menu on right-click or Shift-F10. 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.

The JET Menu should be initialized before any component using it as a context menu.

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) :
$( ".selector" ).ojFoo({ "contextMenu": "#myMenu" });

Get or set the contextMenu option, after initialization:

// getter
var menu = $( ".selector" ).ojFoo( "option", "contextMenu" );

// setter
$( ".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

#data :oj.DataGridDataSource|oj.Collection|Array|Object|null

The data source for the DataGrid. If an array (single or two-dimensional) or oj collection is specified, the widget will automatically create the appropriate adapter for it. A custom data source can be passed in as well. To specify a row header key or index pass in an Object as such: {"data": {oj.DataGridDataSource|oj.Collection|Array}, "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":[1,2,3]});

Initialize the data grid with a two-dimensional array:

$( ".selector" ).ojDataGrid({ "data":['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":['1','2','Cat'],['1','4','Dog'],['5','1','Bird']}});

Initialize the data grid with an oj.Collection:

$( ".selector" ).ojDataGrid({ "data": new oj.Collection.extend({url: 'file.json'}) });

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

$( ".selector" ).ojDataGrid({ "data":{ "data":new oj.Collection.extend({url: 'file.json'}), "rowHeader":'key' }});

Initialize the data grid with a custom data source

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

#dnd :Object

Specifies whether the user is permitted to reorder the rows within the same datagrid using drag and drop.

Specify an object with the property "reorder" set to 'disable' to enable reordering. Setting the "reorder" property to 'disable', or setting the "dnd" property to 'null (or omitting it), disables reordering support.
Default Value:
  • false
Source:
Example

Initialize the data grid to enable single row reorder:

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

#emptyText :String|null

The text to display when there are no data in the Grid. If it is not defined, then a default empty text is extracted from the resource bundle.
Default Value:
  • "There are no data to display"
Source:
Example

Initialize the data grid with the empty text set to 'no data':

$( ".selector" ).ojDataGrid({ "data":data, "emptyText": "no data" });

#gridlines :Object.<string, string>

Specifies whether or not the horizontal/vertical grid lines are visible. Gridlines are visible by default, and must be set to 'hidden' in order to be hidden.
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"} });

#renderer :function(Object)|null

The renderer function that renders the content of the row header cell. The headerContext contains information about the header such as its index, axis, data, and parent element. The function returns either a String or a DOM element of the content inside the header. If the developer chooses to manipulate the header 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:
Example

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();}}}});

#renderer :function(Object)|null

The renderer function that renders the content of the column header cell. The headerContext contains information about the header such as its index, axis, data, and parent element. The function returns either a String or a DOM element of the content inside the header. If the developer chooses to manipulate the header 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:
Example

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();}}}});

#renderer :function(Object)|null

The renderer function that renders the content of the cell. The headerContext contains information about the header such as its index, axis, data, and parent element. The function returns either a String or a DOM element of the content inside the header. If the developer chooses to manipulate the header 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:
Example

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

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

#resizable :Object.<string, string>

Whether the header width or height or both can be resize. Note that for column header, function cannot be used with "height" and for row header, function cannot be used with "width".
Default Value:
  • {"width": "disable", "height": "disable"}
Source:
Example

Initialize the data grid with row header height resizable only:

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

#resizable :Object.<string, string>|null

Whether the header width or height or both can be resize. Note that for column header, function cannot be used with "height" and for row header, function cannot be used with "width".
Default Value:
  • {"width": "disable", "height": "disable"}
Source:
Example

Initialize the data grid with column header width resizable only:

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

#rootAttributes :Object|undefined

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 root element at creation time.

The specified class and style are appended to the current class and style, respectively. All other attributes overwrite any existing value.

Setting this option after component creation has no effect.

Default Value:
  • undefined
Inherited From:
Source:
Example

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

$( ".selector" ).ojFoo({ "rootAttributes": {
  'id': 'myId', 
  'style': 'max-width:100%; color:blue;', 
  'class': 'my-class'
}});

#scrollPosition :Object.<string, Object>|null

The index or key of the row and/or column to display initially in the data grid.
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"}}}); 

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

#sortable :string

Whether or not the field bounded by this header is sortable. The data source associated with the DataGrid must have the sort function defined.
Default Value:
  • "auto"
Source:
Example

Initialize the data grid with row header sort disabled:

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

#sortable :string

Whether or not the field bounded by this header is sortable. The data source associated with the DataGrid must have the sort function defined.
Default Value:
  • "auto"
Source:
Example

Initialize the data grid with column header sort disabled:

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

#style :string|null

The CSS style to set on the header element.
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;}}}});           

#style :string|null

The CSS style to set on the header element.
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;}}}});           

#style :string|null

The CSS style to set on the cell.
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 column header to have a green background:

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

#template :string|null

The template to use to render the row headers
Default Value:
  • null
Source:

#template :string|null

The template to use to render the column headers
Default Value:
  • null
Source:

#template :string|null

The template to use to render the cells
Default Value:
  • null
Source:

Events

#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 Element the header Element which was resized
size string the new pixel size string (ex: '75px')
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 ) {} );

#select

Triggered when a portion of the data grid is selected
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
selection Array the datagrid selection object
Source:
Examples

Initialize the data grid with the select callback specified:

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

Bind an event listener to the ojselect event:

$( ".selector" ).on( "ojselect", 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 header Element 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

#getNodeBySubId(locator) → {Element|null}

Return the subcomponent node represented by the documented locator attribute values.
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 component name - 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.

Inherited From:
Source:
Returns:
the subcomponent located by the subId string passed in locator, if found.
Type
Element | null

#getSubIdByNode(node) → {string|null}

Return the subId string for the given child DOM node
Parameters:
Name Type Description
node Element child DOM node
Inherited From:
Source:
Returns:
- the subId for the DOM node or null when none is found
Type
string | null

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

This method has several overloads, which gets and set component options.

The first overload accepts a single optionName param as a string, and returns the current value of that option.

The second overload accepts two params, an optionName string and a new value to which that option will be set.

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

The fourth overload accepts a single map of option-value pairs to set on the component.

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:

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

Second overload: set one option:

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

Third overload: get all options:

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

Fourth overload: set one or more options:

$( ".selector" ).ojFoo( "option", { disabled: true } ); // 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" );

#selection(ranges)

If no arguments are passed in, gets the current selections in the Grid. Returns an empty array if there's no selection. Returns "all" if everything is selected. Returns an array of range objects for all other cases.

If argument passed in, sets the current selections in the Grid

Parameters:
Name Type Argument Description
ranges Array.<Object> <optional>
optional, an array of selection objects
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Examples

Get the current selection:

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

Set a row selection on the grid:

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

Set a cell selection on the grid:

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

Non-public Methods

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

<protected> #_AfterCreate()

This method is called after _ComponentCreate. 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:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_ComponentCreate()

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

Overrides of this method should call this._super first.

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

<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 from _create() and 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 if directional islands and component reparenting (e.g. popups) should coexist.)

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}

Gets the saved attributes for the provided element. This is usually the original list of attributes set on the element.
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.
Type
Object

<protected> #_InitOptions()

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. No other work should be done in this method. See below for details.

Overrides of this method should call this._super first.

Usage:

  • If the component has an option like disabled that can be set from the DOM at create time, then the "get from DOM" logic should live in this method. E.g. a typical override might say "if the disabled option still has its initial value of undefined (i.e., the option has not been set), then get the DOM property and set it on the option." (See also next bullet.)
  • For attributes that live on the component's root node, keep in mind that anything specified via the rootAttributes option will not be placed on the DOM until _AfterCreate. So when getting attributes from the root node, components must first look in the rootAttributes option, and then, only if the attribute is not found there, look on the component root (if it already exists).
  • For options that, unlike disabled, have no corresponding DOM property, and are not otherwise set from the DOM, there is nothing to do in this method.
  • Do NOT set anything on the DOM in this method (like the resolved disabled value, or any rootAttributes values). The resolved option values should be set on the DOM later, in _ComponentCreate, and the rootAttributes values are set in baseComponent._AfterCreate.
Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_RestoreAttributes()

Restores the saved element's attributes
Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_SaveAttributes(element)

Saves the element's attributes within an internal variable to be reset during the destroy function 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:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_SetRootAttributes()

Reads the rootAttributes option, and sets the root attributes on the component's root DOM element.

class and style are appended to the current class and style, respectively. All other attributes overwrite any existing value.

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