Skip to main content

The Plug-in

See below documentation on how to manipulate Enhanced Grid Pro and its data.

Events

Before Refresh

Enhanced Grid Pro exposes the native APEX Before Refresh event.

Triggered:

  • before data in the Grid is reloaded

After Refresh

Enhanced Grid Pro exposes the native APEX After Refresh event.

Triggered on:

  • data load (DATA_LOADED)
  • new row created (AFTER_CREATE_ROW)
  • row refreshed (ROW_REFRESHED)
  • successful save (AFTER_SAVE)

Event Data

PropertyDescription
this.data.actionInformation on which action this event was triggered (one of the options above)
this.data.offsetFrom which index data was loaded (only available on DATA_LOADED, AFTER_CREATE_ROW, AFTER_SAVE)
this.data.countHow many rows were loaded (only available on DATA_LOADED, AFTER_CREATE_ROW, AFTER_SAVE)
this.data.ucGridInstance of Grid plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Change

Enhanced Grid Pro exposes the native APEX Change event.

Triggered:

  • When the value of a Grid's cell has changed

Note: To add Dynamic Action on change event, please use the following settings:

  • Event: Change
  • Selection Type: jQuery Selector
  • jQuery Selector: .col_COLNAME (example: .col_ENAME)

Explanation: Oracle APEX has a bug that doesn't allow using "Selection Type" = "Column(s)".

Event Data

PropertyDescription
this.data.changesArrArray of changes.

For each change the following data is provided:
row - row index of the edited cell
column - column index of the edited cell
oldValue
newValue
this.data.sourceString that identifies the source of the change.

Examples:
edit - normal change of cell's value
Autofill.fill - when fill handle was used to change value(s)
CopyPaste.paste - when a value was pasted into the cell
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

After save

Enhanced Grid Pro exposes the After Save [UC - Enhanced Grid Pro] event.

Triggered:

  • after data is successfully saved (only triggered when there was something to save)

Event Data

PropertyDescription
this.data.upsertedRowsData that was inserted/updated.
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Click

Enhanced Grid Pro exposes the Click [UC - Enhanced Grid Pro] event.

Triggered:

  • After a Grid's cell has been clicked

Event Data

PropertyDescription
this.data.rowrow index of the cell
this.data.columncolumn index of the cell
this.data.triggeringElementTD element
this.data.originalEventMouseEvent object
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Cell initialization

Enhanced Grid Pro exposes the Cell Initialization [UC - Enhanced Grid Pro] event.

Triggered:

  • After the user enters edit mode in a Grid's cell

Event Data

PropertyDescription
this.data.rowrow index of the cell
this.data.columncolumn index of the cell
this.data.triggeringElementTD element
this.data.originalEventMouseEvent object
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Cells selection

Enhanced Grid Pro exposes the Cells Selection [UC - Enhanced Grid Pro] event.

Triggered:

  • after Grid's cells were selected (one or multiple cells)

Event Data

PropertyDescription
this.data.rowStartrow index where the selection starts
this.data.columnStartcolumn index where the selection starts
this.data.rowEndrow index where the selection ends
this.data.columnEndcolumn index where selection ends
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Cell Mouse Over

Enhanced Grid Pro exposes the Cell Mouse Over [UC - Enhanced Grid Pro] event.

Triggered when mouse cursor enters the cell.

Event Data

PropertyDescription
this.data.rowrow index of the cell
this.data.columncolumn index of the cell
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Cell Mouse Out (available from v24.1.1)

Enhanced Grid Pro exposes the Cell Mouse Out [UC - Enhanced Grid Pro] event.

Triggered when mouse cursor leaves the cell.

Event Data

PropertyDescription
this.data.rowrow index of the cell
this.data.columncolumn index of the cell
this.data.ucGridInstance of the Enhanced Grid Pro plug-in (on which you can call JavaScript functions available - e.g. ucGrid.getValue(...))

Cell Highlighting Changed (available from v23.2)

Enhanced Grid Pro exposes the Cell Highlighting Changed [UC - Enhanced Grid Pro] event.

Triggered on:

  • One or multiple cells highlighted [HIGHLIGHT_ADD]
  • Removed highlighting from one or multiple cells [HIGHLIGHT_REMOVE]
  • Removed all highlighting [HIGHLIGHT_REMOVE_ALL]

Event Data

PropertyDescription
this.data.actionInformation on which action this event was triggered (one of the options above)
this.data.cellsAffected cells (only available on HIGHLIGHT_ADD, HIGHLIGHT_REMOVE)
this.data.cssClassCSS class used to highlight cells (only available on HIGHLIGHT_ADD)

JavaScript functions

JavaScript functions are available to interact with Enhanced Grid Pro and its data.

Call functions this way (replace "STATIC_ID" below with the static ID of your Grid region):

let ucGrid = $("#ucGrid_STATIC_ID").ucGrid("instance");
ucGrid.functionName(...)

Or if you're using one of the events listed above (before/after refresh, change, ...), you can do this:

let ucGrid = this.data.ucGrid;
ucGrid.functionName(...)

version()

Show the version of the Enhanced Grid Pro plug-in.

render()

Rerender the grid.

Useful when calling a function (e.g., "addCssClass") with the parameter "render" set to "false" multiple times.

  • this way, Grid can only be rendered once (after the last call of "addCssClass") - and not after every call of the function
  • Handsontable's "render" function is called (more info).

getData()

Get the grid's data.

Returns an array of arrays with the data.

const ucGrid = $("#ucGrid_STATIC_ID").ucGrid("instance");
ucGrid.getData();
[
[ "data1", "data2", "data3" ],
[ "data4", "data5", "data6" ],
...
]

Want to get the data as an array of objects? You can pass asObjects as a parameter:

const ucGrid = $("#ucGrid_STATIC_ID").ucGrid("instance");
ucGrid.getData({ asObjects: true });
[
{ "COL1": "data1", "COL2": "data2", "COL3": "data3" },
{ "COL1": "data4", "COL2": "data5", "COL3": "data6" },
...
]

refresh()

Reload data in Grid. This does exaxtly the same as the "Refresh" button in Grid's toolbar.

  • Load first set of data again
  • In case when there are unsaved changes, ask user what to do (continue or not)

updateData()

Update data in Grid.

  • Retrieve data from DB and load it into the Grid
  • Keep the scroll position
  • In case when there are unsaved changes, they are lost (no questions asked)

refreshRows(rowIndexesArray)

Refresh Row(s) - get value(s) from DB again and set it/them.

ParameterDescription
rowIndexesArrayarray of rows' indexes that should be refreshed

getValue(row, columnName)

Get the value at a specific cell.

ParameterDescription
rowRow index within Grid
columnNameColumn name

setValue(dataArray, pSuppressChangeEvent=false)

Set value(s).

ParameterDescription
dataArray[[row, columnName, value], ...]

row - row index within Grid
columnName - column name
value - new value of the cell
[pSuppressChangeEvent]Optional.
Default: false
//Example for select list column:
ucGrid.setValue( [[rowIndex, columnName, [{ "d": "Display Value", "r": 999}] ]] );

enableRow(row, render=true)

Enable {row}.

ParameterDescription
rowRow index within Grid
[render]Optional.
Default: true.

Flag whether to render the Grid at the end. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

enableRowColumn(row, columnName, render=true)

Enable {columnName} at given {row} index.

ParameterDescription
rowRow index within Grid
columnNameColumn name
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

disableRow(row, render=true)

Disable {row}.

ParameterDescription
rowRow index within Grid
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

disableRowColumn(row, columnName, render=true)

  • Disable {columnName} at given {row} index.
ParameterDescription
rowRow index within Grid
columnNameColumn name
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

isColumnReadOnly(columnName)

  • Check if Grid's {columnName} is readOnly (disabled).
ParameterDescription
columnNameColumn name

isCellReadOnly(row, columnName)

  • Check if Grid's cell - {columnName} at given {row} index - is readOnly (disabled).
ParameterDescription
rowRow index within Grid
columnNameColumn name

addCssClass(row, columnName, classToAdd, render=true)

Add CSS class {classToAdd} to the cell at ({row}, {columnName}).

ParameterDescription
rowRow index within Grid
columnNameColumn name
classToAddCSS class name to be added
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

addCssClassToRow(row, classToAdd, render=true)

Add CSS class {classToAdd} to all columns in {row}.

ParameterDescription
rowRow index within Grid
classToAddCSS class name to be added
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call of it (it's much faster this way)

addCssClassToColumn(columnName, classToAdd, render=true)

Add CSS class {classToAdd} to {columnName} in all rows.

ParameterDescription
columnNameColumn name
classToAddCSS class name to be added
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call of it (it's much faster this way)

removeCssClass(row, columnName, classToRemove, render=true)

Remove CSS class {classToRemove} from the cell at ({row}, {columnName}).

ParameterDescription
rowRow index within Grid
columnNameColumn name
classToRemoveCSS class name to be removed
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

removeCssClassFromRow(row, classToRemove, render=true)

Remove CSS class {classToRemove} from all columns in {row}.

ParameterDescription
rowRow index within Grid
classToRemoveCSS class name to be removed
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

removeCssClassFromColumn(columnName, classToRemove, render=true)

Remove CSS class {classToRemove} from {columnName} in all rows.

ParameterDescription
columnNameColumn name
classToRemoveCSS class name to be removed
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

setTooltip(row, columnName, tooltipText, render=true)

Set the tooltip of a cell at ({row}, {columnName}). Supports HTML.

ParameterDescription
rowRow index within Grid
columnNameColumn name
tooltipTextTooltip text
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

Example - render tooltip on all columns:

const ucGrid = $("#ucGrid_STATIC_ID").ucGrid("instance");
const data = grid.getData({ asObjects: true });
apex.debug.info("Adding tooltips to grid", {
grid,
data,
});

let rowNo = 0;

// loop over rows
for (const row of data) {
// loop over columns
for (const [colName, value] of Object.entries(row)) {
let tooltip = value;

// for select list columns, concat all display values
if (Array.isArray(value)) {
apex.debug.info("value is LOV", value);
// join all values with comma
tooltip = value.map((v) => v?.d).join(", ");
}

apex.debug.info("Adding tooltip to column", {
rowNo,
colName,
tooltip,
});

// performance: don't re-render the grid after each tooltip
grid.setTooltip(rowNo, colName, tooltip, false);
}
rowNo++;
}

// performance: re-render the grid only once at the end
grid.render();

removeTooltip(row, columnName, tooltipText, render=true)

Remove any previously set tooltip of a cell at ({row}, {columnName}).

ParameterDescription
rowRow index within Grid
columnNameColumn name
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

hideColumn(columnName, render=true)

Hide column {columnName}.

ParameterDescription
columnNameColumn name
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

showColumn(columnName, render=true)

Show column {columnName}.

ParameterDescription
columnNameColumn name
[render]Optional.
Default: true.

Flag whether to render the Grid at the end or not. When multiple calls to the function are done, you would want to render the Grid only after the last call (it's much faster this way)

getSelected()

Get the selected cell(s).

Returns indexes of the currently selected cells as an array of arrays [[startRow, startCol, endRow, endCol],...].

getSelectedRows()

Get the selected rows.

Returns array with row indexes.

setValidationFunction(columnName, validationFunction)

Set {validationFunction} to given {columnName}.

ParameterDescription
columnNameColumn name
validationFunctionFunction (with two parameters) to validate data. See the example below.

Example:

function validateColSalary(newValue, rowIdx, rowData) {
if (newValue < 1000 || newValue > 2000) {
return "Salary must be between 1000 and 2000";
}
}
ParameterDescription
newValueValue of edited
rowIdxNumerical row index
rowDataObject with the column ID as keys and their values. Note that the changed column value is still the old one. Check newValue for validations.

Full implemetation example:

const ucGrid = $("#ucGrid_STATIC_ID").ucGrid("instance");

ucGrid.setValidationFunction("SAL", (newValue, rowIdx, rowData) => {
apex.debug.info("Validation function for SAL", {
newValue,
rowIdx,
rowData,
});

if (newValue >= 10 && rowData.JOB !== "Manager") {
// return error message
return "Sal must be less than 10";
}
);

save(originalRequest)

Save data in Grid. Only does something if there are changes to be saved.

ParameterDescription
[originalRequest]Optional.
If provided, page will be submitted with request name {originalRequest} once the Grid's data is successfully saved.

reset()

Reset config (sort, filter) and load data again.

getFiltersUsed()

Available from v24.1.

Returns all filters that are currently used - as JavaScript array.

Initialization Javascript Function

Additionally to plug-in declarative attributes, some settings can be done via plug-in's "Initialization Javascript Function".

ParameterComponentDescriptionAvailable from
batchSizeGridDefine how many rows are loaded every time the next batch of data is requested (triggered on scroll event).
Defined value will only be used when next batch of data is requested, and NOT on initial load.
v23.2
resetConfigOnInitGridBy default, Sorting and Filtering used (defined by user) are kept for user's current session.
To reset Sort and Filter (on page load, before data gets loaded) regardless of the user's session, you can set this to "true".
v23.2
trimSelectListChoicesGrid columnUsed with select list column.

By default, this is set to "true" - and it means: when a select list (with possible values) is opened, it's as wide as the column itself.
You can override this by setting "trimSelectListChoices" to "false". When "false", select list width is defined by the longest value in it.
v23.2
expectReturnValuesOnPasteGrid columnUsed with select list column.

By default, this is set to "false" - and it means: when pasting data from an external source (e.g. Excel or another Grid instance in the application), a DISPLAY value is expected.
You can override this by setting "expectReturnValuesOnPaste" to "true". When "true", Grid will expect the RETURN values to be pasted into given select list column.

This parameter is not used when copy-pasting data within single Grid instance.
v24.1
    function (pOptions) {
//Grid parameters
pOptions.batchSize = 20;
pOptions.resetConfigOnInit = true;

//Grid's select list column parameters
pOptions.columns['DEPTNO'] = {
trimSelectListChoices: false,
expectReturnValuesOnPaste: true
};

return pOptions;
}

Translation Messages

The plug-in supports the following Oracle APEX Text Messages.

Translation CodeTranslation default textUsed in JavaScript
UC_GRID.CORRECT_ERRORS_BEFORE_SAVECorrect errors before saving.Yes
UC_GRID.SELECT_ONLY_ONE_ROW_TO_DUPLICATESelect only 1 row to duplicate.Yes
UC_GRID.PASTE_DATA_TOO_MANY_COLUMNSIt seems that data (you wanted to paste) has too many columns. Please check.Yes
UC_GRID.CREATE_ROW_PREVENTEDYou wanted to paste data that would require us to add new rows.
But according to settings, that is not allowed.
Yes
UC_GRID.TOOLTIP_NOT_POSSIBLESetting Tooltip is only possible for row indexes greater than 0.Yes
UC_GRID.RELOAD_DATA_QUESTIONReload Data?
Changes will not be saved.
Yes
UC_GRID.CHANGES_SAVEDChanges saved!Yes
UC_GRID.UNSAVED_CHANGES_EXISTUnsaved changes exist.
Continue?
Yes
UC_GRID.DELETE_ROWS_CONFIRMDo you really want to delete row(s)?Yes
UC_GRID.CONTEXT_MENU.ADD_ROWAdd rowYes
UC_GRID.CONTEXT_MENU.DUPLICATE_ROWDuplicate rowYes
UC_GRID.CONTEXT_MENU.DELETE_ROWSDelete row(s)Yes
UC_GRID.CONTEXT_MENU.REFRESH_ROWSRefresh row(s)Yes
UC_GRID.CONTEXT_MENU.UNDOUndoYes
UC_GRID.CONTEXT_MENU.REDORedoYes
UC_GRID.CONTEXT_MENU.COPYCopyYes
UC_GRID.CONTEXT_MENU.CUTCutYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLSHighlight cellsYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.CLEAR_ALLClear AllYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.CLEAR_SELECTIONClear SelectionYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.NOT_AVAILABLE_ON_SELECTED_ROWSIt's not possible to use highlighting with selected cells(s) / row(s).Yes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.YELLOWYellowYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.ORANGEOrangeYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.GREENGreenYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.BLUEBlueYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.PINKPinkYes
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.PURPLEPurpleYes
UC_GRID.VALIDATION.VALUE_REQUIREDValue is requiredYes
UC_GRID.VALIDATION.VALUE_TOO_LONGValue too long. Maximum characters allowed: %0Yes
UC_GRID.VALIDATION.VALUE_NOT_NUMERICValue is not numeric.\nOnly decimal separators can be used.Yes
UC_GRID.VALIDATION.LOV_VALUE_NOT_VALIDValue is not valid.Yes
UC_GRID.BUTTON.SAVESaveNo
UC_GRID.BUTTON.RELOAD_DATAReload DataNo
UC_GRID.BUTTON.ACTIONSActionsNo
UC_GRID.BUTTON.ADD_ROWAdd RowNo
UC_GRID.BUTTON.DELETED_ROWSDeleted rows:No
UC_GRID.BUTTON.RESETResetNo
UC_GRID.BUTTON.RESET_HTML_TITLEResetNo
UC_GRID.BUTTON.MAXIMIZEMaximizeNo
UC_GRID.NO_DATA_FOUNDNo Data FoundNo
UC_GRID.TOTAL_ROWSTotalNo
UC_GRID.SAVED_REPORT.DELETE_CONFIRMDo you really want to delete saved report?Yes
UC_GRID.SELECT_LIST.SAVED_REPORTSSaved ReportsNo
UC_GRID.SELECT_LIST.SAVED_REPORTS.DEFAULTDefaultNo
UC_GRID.SELECT_LIST.SAVED_REPORTS.ALTERNATIVEAlternativeNo
UC_GRID.SELECT_LIST.SAVED_REPORTS.PRIVATEPrivateNo
UC_GRID.ACTIONS.SELECT_COLUMNSSelect ColumnsNo
UC_GRID.ACTIONS.REPORTReportNo
UC_GRID.ACTIONS.REPORT.SAVESaveNo
UC_GRID.ACTIONS.REPORT.SAVE_ASSave AsNo
UC_GRID.ACTIONS.REPORT.DELETEDeleteNo
UC_GRID.ACTIONS.REPORT.PRIMARY_REPORT_NAMEPrimary ReportNo

Supported Languages (numeric columns)

Numeric columns in Grid support multiple languages via using numbrojs library. This is important to use the right thousand/decimal separators. For the full list, please see this link: https://numbrojs.com/languages.html#supported-languages

Debug

Enhanced Grid Pro can be debugged using APEX debug mode in the browser console (client-side) and the built-in debug.

Please use debug level "App Trace" to see logs in browser console.

Help in the Page Designer

Enhanced Grid Pro plug-in attributes are exposed along with help text built into the page designer in the Help tab. Example help for the plug-in attribute Settings \ Options is presented below: