Table of Contents
- 1 Table of Contents
- 2 Introduction
- 2.1 Features at Glance
- 2.1.1 Graphic Representation
- 2.1.2 Instant Interaction
- 2.1.3 Built-in Validation
- 2.1.4 Easy-to-Use
- 2.1.5 Three States Supported
- 2.1.6 Extended Change Event
- 2.1 Features at Glance
- 3 Requirements
- 4 The Plug-in
- 4.1 Checkbox States
- 4.1.1 Checked
- 4.1.2 Not Checked
- 4.1.3 Null Value
- 4.2 APEX Integration
- 4.2.1 Accessibility
- 4.2.2 Read-only State
- 4.2.3 Dynamic Actions
- 4.2.3.1 Set Value
- 4.3 Events
- 4.3.1 The Plug-in Change Event
- 4.3.2 Event Data
- 4.3.3 Debug
- 4.4 Validation
- 4.5 Attributes
- 4.5.1 Application Attributes
- 4.5.2 Standard
- 4.5.3 Custom
- 4.6 Help in the Page Designer
- 4.1 Checkbox States
- 5 Usage Guide
- 6 Sample Application
- 6.1 Checkbox states
- 6.2 Integration
- 6.3 Styling
Introduction
Fill the gap in the interactive grid and enhance it with the missing checkbox component. Let your users change Yes/No columns in a convenient way - with a simple click on a checkbox or icon.
With the Interactive Grid Checkbox Pro plug-in, you don't have to write custom JavaScript code and CSS rules to implement checkboxes in your grids. You don't even have to bother with enabling edit mode in the grid. Simply change the column type to Interactive Grid Checkbox Pro and save your time and energy for more challenging tasks.
Features at Glance
Graphic Representation
The column value can be rendered as an HTML checkbox input or as an icon.
Instant Interaction
The end-user can change the state of the column without enabling edit mode in an interactive grid.
Built-in Validation
Built-in validation is used to prevent invalid data from being saved.
Easy-to-Use
No additional JavaScript configuration needed. Just change the column type to the plug-in and set the default values for the checked and unchecked states.
Three States Supported
The checkbox can be checked, not checked, or null.
Extended Change Event
Modified row data is exposed via the plug-in on change event.
Requirements
The table below describes the requirements that were used to define the plug-in scope.
Requirement | Interactive Grid Checkbox Pro | |
|---|---|---|
| 1 | The plug-in should respect a column’s read-only state |
The plug-in renders a checkbox (or icon) in a column’s read-only state but it doesn’t change the state. Additionally, the checkbox is greyed. |
| 2 | The plug-in should support 3 states: checked, not checked, and null of an interactive grid column. |
The plug-in supports all 3 states and allows defining a default value for new interactive grid rows. |
| 3 | The plug-in should allow the state of a checkbox to change without enabling interactive grid edit mode. |
The plug-in exposes attributes which enable or disable the possibility to change the checkbox state outside of interactive grid edit mode. Saving an interactive grid’s changes is necessary to preserve any changes. |
| 4 | The plug-in should allow changing the looks of the checkbox. |
The plug-in supports the native HTML checkbox and allows defining APEX icons for checkbox checked and not checked states. The NULL state doesn’t render a checkbox or icon. |
| 5 | The plug-in should provide extra information about the purpose of a checkbox. |
The plug-in supports the title attribute for checkboxes and icons. Hovering over a checkbox/icon displays the title. |
| 6 | The plug-in should raise an error when the current value is invalid. |
The plug-in has a built-in validation function which checks (on interactive grid save) whether an item’s value is NULL, Checked Value, or Not Checked Value. If the current value is out of scope the error is raised. |
| 7 | The plug-in should expose a change event when checkbox state is changed |
The plug-in triggers the native change event and the plug-in change event with additional data describing the currently edited row of an interactive grid. |
The Plug-in
The Interactive Grid Checkbox Pro is an item type plug-in for Oracle Application Express (APEX).
Checkbox States
Checked
The value representing the checked state must be set using the plug-in Value When Checked attribute. When a column contains this value, the plug-in renders a checked checkbox or the icon representing the checked state. An icon can be selected using the plug-in Icon Checked attribute.
Not Checked
The value representing the not checked state must be set using the plug-in Value When Not Checked attribute. When a column contains this value, the plug-in renders an unchecked checkbox or the icon representing the not checked state. An icon can be selected using the plug-in Icon Not Checked attribute.
Null Value
When the column value is NULL, the interactive grid will not render a checkbox or an icon. However, activated columns containing a NULL value allow the end-user to set a checked or not checked value.
When NULL is used as the default value for new rows, a new row's checkbox/icon is semi-transparent. After changing the state of a new row checkbox/icon there is no way to make it null again without an additional dynamic action that sets the value to null.
Still, after focusing on the column (in interactive grid edit mode) containing the null value it is possible to change the value according to the plug-in configuration.
APEX Integration
Accessibility
Keyboard-only actions are supported. In an interactive grid, read mode navigate to a cell containing the plug-in and press the Enter key to activate interactive grid edit mode. When the plug-in checkbox or icon is in focus, you can change the state by pressing the Spacebar key.
Read-only State
The read-only column setting is supported by disabling the ability of the user to change the value when they click on the checkbox (or icon).
Dynamic Actions
Set Value
The plug-in supports the native Set value dynamic action. It can be used to set the value of the column based on the value in other columns.
Events
The Plug-in Change Event
The plug-in exposes the Change [United Codes Interactive Grid Checkbox] event. The difference between this event and the native column Change event is that it reveals additional data through this.data.
Event Data
Property | Description |
|---|---|
this.data.region | The region interface returned from the execution of apex.region. |
this.data.grid | The interactiveGridView interface returned from the getViews interactiveGrid widget method. |
this.data.record | The result of the grid's widget method getActiveRecord. |
this.data.recordId | Record id returned by the model interface using the getRecordId method. |
this.data.column | The column name on which the plug-in change event occurred. |
this.data.value | The current value of the given column in the given record. |
Debug
The plug-in can be debugged using APEX debug mode in the browser console (client-side) and built-in debug.
Validation
The plug-in has built-in validation which is executed when the interactive grid is saved. If the value of a column using the plug-in is equal to the Value When Checked or Value When Not Checked attribute or is NULL then validation is successful. Otherwise, the built-in validation raises an error.
The validation error message can be customized using UC_IG_CHECKBOX_VALIDATION APEX Translation Text. Use %0 to reference a column label and %1 to reference the invalid value.
Attributes
Application Attributes
The plug-in doesn’t expose any application attributes.
Standard
Attribute | Checked |
|---|---|
Is Visible Widget |
|
Standard Form Element |
|
Session State Changeable |
|
Has Read Only Attribute |
|
Has Escape Special Characters Attribute |
|
Has Quick Pick Attributes |
|
Has Source Attributes |
|
Format Mask Date Only |
|
Format Mask Number Only |
|
Has Element Attributes |
|
Has Width Attributes |
|
Has Height Attribute |
|
Has Element Option Attribute |
|
Has Placeholder Attribute |
|
Has Icon Attribute |
|
Has Encrypt Session State Attribute |
|
Has List of Values |
|
Has LOV Display Null Attributes |
|
Has Cascading LOV Attributes |
|
Join LOV for Column Display |
|
Has Filter |
|
Has Link |
|
Has "'Initialization JavaScript Code" Attribute |
|
Custom
These attributes are exposed in the page designer when the column type is set to the plug-in.
Attribute | Dependent on | Type | Description |
|---|---|---|---|
Value When Checked | Not applicable | Text | This attribute value is used when the checkbox is checked. |
Value When Not Checked | Not applicable | Text | This attribute value is used when checkbox is not checked. To use NULL, empty the attribute. |
New Row Default Value | Not applicable | Select List | This attribute value is used as the default value for the checkbox when end-users add a new row to an interactive grid. Available options include:
|
Type | Not applicable | Select List | Defines what the graphical visualization of the column value should be. Available options include:
Icons representing checked and not checked states must be defined using the plug-in attributes Icon Checked and Icon Not Checked. |
Icon Checked | Type | Icon | This attribute allows choosing an icon representing the checked state. This attribute can be used to assign additional custom classes to the icon. |
Icon Not Checked | Type | Icon | This attribute allows choosing an icon representing the not checked state. This attribute can be used to assign additional custom classes to the icon. |
Settings | Not applicable | Checkboxes | This attribute allows defining the behavior of the plug-in. Available options include:
|
Title | Settings | Text | This attribute defines the value of the title tag added to the checkbox or icon. The title is displayed after hovering over the plug-in checkbox or icon. You can use page items substitutions |
Help in the Page Designer
The plug-in attributes are exposed along with help text built into the page designer in the Help tab.
Example help for the Settings \ New Row Default Value plug-in attribute is presented below:
Usage Guide
This section describes an example implementation of the plug-in in an example Oracle APEX application. The usage guide shows the basic implementation of the plug-in and doesn’t describe the plug-in attributes.
Introduction
This usage guide is using the plug-in sample application IG_CHECKBOX_PLUGIN table. In an example application, page 710 is created. On the page, an interactive grid region called Example is created and contains three columns ID, EMP_NAME, and FLAG. The ID and EMP_NAME columns are Display Only and the FLAG column is a Text Field. The interactive grid supports editing and the primary key is set as the ID column.
The FLAG column is a VARCHAR2 column that can store flag values such as:
Y - when checked
N - when not checked
NULL - when the flag is not set
Creating a Plug-in Column
Select the FLAG column
Set Identification \ Type to United Codes IG Checkbox Pro [Plug-in]
Set Settings \ Type to APEX icons
For Settings \ Icon Checked use fa-check-square-o as the default value
For Settings \ Icon Not Checked use the fa-square-o as the default value
For Settings \ Value When Checked use Y as the default value
For Settings \ Value When Not Checked use N as the default value
For Settings \ New Row Default Value use Null as the default value
(Optional) Set Settings \ Settings according to your requirements
Save the page
The resulting page will look as follows:
Test the Implementation
Open page 710 in a browser
Test the checkbox inside and outside of interactive grid edit mode (behavior depends on the plug-in Settings \ Settings)
Sample Application
Interactive Grid Checkbox Pro is delivered with a sample application which describes all of the plug-in’s features with example implementations. The sample application describes and implements the following topics:
Checkbox states
The checkbox states page describes and shows the plug-in’s capability to handle the three states of the flag and how it handles column read-only state.
Integration
The integration page describes how the plug-in is integrated with the Oracle APEX interactive grid.
Styling
The styling page describes how the plug-in renders checkboxes in the different states of the interactive grid.
