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
Property | Description |
---|---|
this.data.action | Information on which action this event was triggered (one of the options above) |
this.data.offset | From which index data was loaded (only available on DATA_LOADED, AFTER_CREATE_ROW, AFTER_SAVE) |
this.data.count | How many rows were loaded (only available on DATA_LOADED, AFTER_CREATE_ROW, AFTER_SAVE) |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.changesArr | Array 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.source | String 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.ucGrid | Instance 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
Property | Description |
---|---|
this.data.upsertedRows | Data that was inserted/updated. |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.row | row index of the cell |
this.data.column | column index of the cell |
this.data.triggeringElement | TD element |
this.data.originalEvent | MouseEvent object |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.row | row index of the cell |
this.data.column | column index of the cell |
this.data.triggeringElement | TD element |
this.data.originalEvent | MouseEvent object |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.rowStart | row index where the selection starts |
this.data.columnStart | column index where the selection starts |
this.data.rowEnd | row index where the selection ends |
this.data.columnEnd | column index where selection ends |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.row | row index of the cell |
this.data.column | column index of the cell |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.row | row index of the cell |
this.data.column | column index of the cell |
this.data.ucGrid | Instance 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
Property | Description |
---|---|
this.data.action | Information on which action this event was triggered (one of the options above) |
this.data.cells | Affected cells (only available on HIGHLIGHT_ADD, HIGHLIGHT_REMOVE) |
this.data.cssClass | CSS 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.
Parameter | Description |
---|---|
rowIndexesArray | array of rows' indexes that should be refreshed |
getValue(row, columnName)
Get the value at a specific cell.
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column name |
setValue(dataArray, pSuppressChangeEvent=false)
Set value(s).
Parameter | Description |
---|---|
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}.
Parameter | Description |
---|---|
row | Row 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.
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column 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}.
Parameter | Description |
---|---|
row | Row 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.
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column 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).
Parameter | Description |
---|---|
columnName | Column name |
isCellReadOnly(row, columnName)
- Check if Grid's cell - {columnName} at given {row} index - is readOnly (disabled).
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column name |
addCssClass(row, columnName, classToAdd, render=true)
Add CSS class {classToAdd} to the cell at ({row}, {columnName}).
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column name |
classToAdd | CSS 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}.
Parameter | Description |
---|---|
row | Row index within Grid |
classToAdd | CSS 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.
Parameter | Description |
---|---|
columnName | Column name |
classToAdd | CSS 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}).
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column name |
classToRemove | CSS 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}.
Parameter | Description |
---|---|
row | Row index within Grid |
classToRemove | CSS 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.
Parameter | Description |
---|---|
columnName | Column name |
classToRemove | CSS 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.
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column name |
tooltipText | Tooltip 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}).
Parameter | Description |
---|---|
row | Row index within Grid |
columnName | Column 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}.
Parameter | Description |
---|---|
columnName | Column 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}.
Parameter | Description |
---|---|
columnName | Column 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}.
Parameter | Description |
---|---|
columnName | Column name |
validationFunction | Function (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";
}
}
Parameter | Description |
---|---|
newValue | Value of edited |
rowIdx | Numerical row index |
rowData | Object 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.
Parameter | Description |
---|---|
[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".
Parameter | Component | Description | Available from |
---|---|---|---|
batchSize | Grid | Define 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 |
resetConfigOnInit | Grid | By 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 |
trimSelectListChoices | Grid column | Used 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 |
expectReturnValuesOnPaste | Grid column | Used 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 Code | Translation default text | Used in JavaScript |
---|---|---|
UC_GRID.CORRECT_ERRORS_BEFORE_SAVE | Correct errors before saving. | Yes |
UC_GRID.SELECT_ONLY_ONE_ROW_TO_DUPLICATE | Select only 1 row to duplicate. | Yes |
UC_GRID.PASTE_DATA_TOO_MANY_COLUMNS | It seems that data (you wanted to paste) has too many columns. Please check. | Yes |
UC_GRID.CREATE_ROW_PREVENTED | You 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_POSSIBLE | Setting Tooltip is only possible for row indexes greater than 0. | Yes |
UC_GRID.RELOAD_DATA_QUESTION | Reload Data? Changes will not be saved. | Yes |
UC_GRID.CHANGES_SAVED | Changes saved! | Yes |
UC_GRID.UNSAVED_CHANGES_EXIST | Unsaved changes exist. Continue? | Yes |
UC_GRID.DELETE_ROWS_CONFIRM | Do you really want to delete row(s)? | Yes |
UC_GRID.CONTEXT_MENU.ADD_ROW | Add row | Yes |
UC_GRID.CONTEXT_MENU.DUPLICATE_ROW | Duplicate row | Yes |
UC_GRID.CONTEXT_MENU.DELETE_ROWS | Delete row(s) | Yes |
UC_GRID.CONTEXT_MENU.REFRESH_ROWS | Refresh row(s) | Yes |
UC_GRID.CONTEXT_MENU.UNDO | Undo | Yes |
UC_GRID.CONTEXT_MENU.REDO | Redo | Yes |
UC_GRID.CONTEXT_MENU.COPY | Copy | Yes |
UC_GRID.CONTEXT_MENU.CUT | Cut | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS | Highlight cells | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.CLEAR_ALL | Clear All | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.CLEAR_SELECTION | Clear Selection | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.NOT_AVAILABLE_ON_SELECTED_ROWS | It's not possible to use highlighting with selected cells(s) / row(s). | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.YELLOW | Yellow | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.ORANGE | Orange | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.GREEN | Green | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.BLUE | Blue | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.PINK | Pink | Yes |
UC_GRID.CONTEXT_MENU.HIGHLIGHT_CELLS.PURPLE | Purple | Yes |
UC_GRID.VALIDATION.VALUE_REQUIRED | Value is required | Yes |
UC_GRID.VALIDATION.VALUE_TOO_LONG | Value too long. Maximum characters allowed: %0 | Yes |
UC_GRID.VALIDATION.VALUE_NOT_NUMERIC | Value is not numeric.\nOnly decimal separators can be used. | Yes |
UC_GRID.VALIDATION.LOV_VALUE_NOT_VALID | Value is not valid. | Yes |
UC_GRID.BUTTON.SAVE | Save | No |
UC_GRID.BUTTON.RELOAD_DATA | Reload Data | No |
UC_GRID.BUTTON.ACTIONS | Actions | No |
UC_GRID.BUTTON.ADD_ROW | Add Row | No |
UC_GRID.BUTTON.DELETED_ROWS | Deleted rows: | No |
UC_GRID.BUTTON.RESET | Reset | No |
UC_GRID.BUTTON.RESET_HTML_TITLE | Reset | No |
UC_GRID.BUTTON.MAXIMIZE | Maximize | No |
UC_GRID.NO_DATA_FOUND | No Data Found | No |
UC_GRID.TOTAL_ROWS | Total | No |
UC_GRID.SAVED_REPORT.DELETE_CONFIRM | Do you really want to delete saved report? | Yes |
UC_GRID.SELECT_LIST.SAVED_REPORTS | Saved Reports | No |
UC_GRID.SELECT_LIST.SAVED_REPORTS.DEFAULT | Default | No |
UC_GRID.SELECT_LIST.SAVED_REPORTS.ALTERNATIVE | Alternative | No |
UC_GRID.SELECT_LIST.SAVED_REPORTS.PRIVATE | Private | No |
UC_GRID.ACTIONS.SELECT_COLUMNS | Select Columns | No |
UC_GRID.ACTIONS.REPORT | Report | No |
UC_GRID.ACTIONS.REPORT.SAVE | Save | No |
UC_GRID.ACTIONS.REPORT.SAVE_AS | Save As | No |
UC_GRID.ACTIONS.REPORT.DELETE | Delete | No |
UC_GRID.ACTIONS.REPORT.PRIMARY_REPORT_NAME | Primary Report | No |
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: