Oracle APEX integration
The plug-in integrates with Oracle APEX using the JavaScript API and page designer item attributes.
Debug mode
When Oracle APEX debug mode is enabled, the plug-in:
- produces browser console logs (Oracle APEX debug levels are used)
- produces PL/SQL logs available in APEX View Debug
Dynamic Actions
The table below presents supported native Oracle APEX dynamic actions.
| Dynamic Action | Description |
|---|---|
| Set value | Sets a new rich text value. The plug-in respects the Suppress Change Event flag. |
| Clear | Resets rich text HTML to empty value. Triggers change event. |
| Disable | Disables the Froala editor. |
| Enable | Enables the Froala editor. |
| Hide | Hides the Froala editor. |
| Show | Shows the Froala editor. |
| Refresh | Fetches the draft CLOB value from the session state and replaces the current rich text HTML. |
| Set Focus | Sets focus on the Froala editor. |
Help in the Page Designer
The plug-in attributes are available in the page designer with built-in Help. Built-in help is only the supporting documentation available in the page designer and only describes some of the plug-in features.
Native JavaScript API
The table below presents the supported native Oracle APEX JavaScript API.
| API | Description |
|---|---|
apex.item.getValue | Returns the current value (HTML) of the Froala editor |
apex.item.addValue | Adds the value to the Froala editor |
Native JavaScript events
The plug-in is listening and triggering Oracle APEX native JavaScript events.
Change
The plug-in triggers a native change event (change) without additional event data.
The event is triggered when:
- dynamic action Refresh on item implementing the plug-in is finished
- the end-user leaves the editor after modifying rich HTML text
- native APEX JavaScript API
apex.item.addValueis executed
Before Refresh
The plug-in triggers a native before refresh event (apexbeforerefresh) before an item is refreshed. The plug-in extends the native event with extra data indicating whether an item refresh event is triggered by the native Refresh dynamic action or is triggered by the supporting dynamic action plug-in (Reset value).
The event is triggered along with the data described below.
| Property | Type | Description |
|---|---|---|
this.data.reason | Text | Indicates what action triggered the event. |
The this.data.reason might be set to the following values:
froalaresetclob- an item is refreshed by the supporting plug-inapexdarefresh- an item is refreshed by the native Refresh dynamic action
After Refresh
The plug-in triggers a native after refresh event (apexafterrefresh) after an item is refreshed. The event is triggered along with the plug-in data indicating whether an item was refreshed by the native Refresh dynamic action or was triggered by the supporting dynamic action plug-in (Reset value).
The event is triggered along with the data described below.
| Property | Type | Description |
|---|---|---|
this.data.reason | Text | Indicates what action triggered the event. |
The this.data.reason might be set to the following values:
froalaresetclob- an item is refreshed by the supporting plug-inapexdarefresh- an item is refreshed by the native Refresh dynamic action
Session State
The plug-in supports CLOB values across Oracle APEX versions, starting with Oracle APEX 19.2. To handle CLOB values in Oracle APEX versions prior to 22.2, a supporting process plug-in is required for reading, inserting, and updating CLOB values in the database.
For Oracle APEX 22.2 onwards, when APEX introduced session state CLOB support, the plug-in relies on APEX's built-in CLOB support.
Loading CLOB values without supporting process plug-in in Oracle APEX before version 22.2 is possible when the value doesn't exceed the VARCHAR2 limitation. However, attempting to load a CLOB value larger than 32,767 characters raises an Oracle APEX engine error.
Known Issues
Despite the introduction of CLOB support in Oracle APEX 22.2, using the page item source attribute to load a CLOB value can cause issues. Page item source types such as PL/SQL Expression and PL/SQL Function Body should theoretically support CLOB values exceeding the VARCHAR2 limitation (32,767 characters). However, in reality, they raise an error at the APEX engine level, which is beyond the plug-in's control.
The plug-in collection
The plug-in uses the APEX collection named UC_FROALA to handle CLOB values and images added to rich text HTML. The collection is shared for all plug-in instances in an application.
The plug-in stores the following information in the collection:
- CLOB value of an on-load CLOB
- CLOB value of a draft CLOB
- images added to the rich text HTML by the end-user
- classes applied to an item using page designer
- Oracle APEX process implementing the supporting process plug-in
The plug-in collection uses columns c001 and c002 to identify which plug-in instance meta-data is stored in the collection row. The c001 is always used to hold an item name (implementing the plug-in), and column c002 describe what kind of information is stored in a row:
ONLOAD- an on-load CLOB value and metadataDRAFT- a draft CLOB value and metadataIMAGE- an image added/removed to/from rich text HTMLCLASS- classes added to an itemLOAD- APEX process meta-data used to load CLOB value
On-load CLOB
When the plug-in is initialized, the on-load CLOB is the initial CLOB value.
The table below presents the collection columns used to describe the on-load CLOB.
| Column | Value description |
|---|---|
| c001 | An item name implementing the plug-in |
| c002 | Always set to ONLOAD |
| n001 | The current CLOB checksum value |
| n002 | The current CLOB length |
| clob001 | The current CLOB contents |
Draft CLOB
The draft CLOB is the CLOB value updated by the end-user on page submission or end user's demand using the supporting dynamic action plug-in. The draft CLOB is used to update the CLOB value in the database using the supporting process plug-in.
The table below presents the collection columns describing a draft CLOB.
| Column | Description |
|---|---|
| c001 | An item name implementing the plug-in |
| c002 | Always set to DRAFT |
| n001 | The current CLOB checksum value |
| n002 | The current CLOB length |
| clob001 | The current CLOB contents |
Difference between on-load CLOB and draft CLOB
The on-load CLOB and draft CLOB are created simultaneously when the plug-in is rendered on page load. On-load and draft CLOB have the same value, length, and checksum until the end-user submits a page or executes the supporting dynamic action plug-in updating a CLOB value.
The on-load CLOB value is preserved until the next page load so it can be used to perform CLOB value checksum validation. See section Validation \ Understanding CLOB checksum validation to learn more about the built-in plug-in validation.
Images
Whenever the end-user adds (or removes) image to (from) rich text, the plug-in updates the plug-in APEX collection. The table below presents what image information is stored in the plug-in collection.
| Column | Description |
|---|---|
| c001 | An item name implementing the plug-in. |
| c002 | Must equal IMAGE. |
| c003 | An unique image ID assigned by the plug-in, for example, ui-id-1. |
| c004 | Flag Y/N indicating whether an image was already embedded in rich text when the plug-in was initialized. |
| c005 | Flag Y/N indicating whether an image was embedded in rich text after the plug-in was initialized. |
| c006 | Flag Y/N indicating whether an image was removed from rich text HTML after the plug-in was initialized. |
| c007 | Flag Y/N indicating whether an image is a base64 image. |
| c008 | Flag Y/N indicating whether an image was uploaded using the plug-in RESTful service. |
| c009 | Flag Y/N indicating whether an image can be safely removed from the database. An uploaded image can be safely removed from the database when an image URL is not shared with other images. |
| c010 | An image URL property. |
| c011 | An image's current ID stored in the database. |
Classes
The table below presents the collection columns describing class names added to the plug-in item using an attribute Item \ Appearance \ CSS Classes.
| Column | Description |
|---|---|
| c001 | An item name implementing the plug-in. |
| c002 | Must eual CLASS. |
| c010 | The provided classes in the page designer. |
Processes
The table below presents the collection columns describing processes used to load CLOB value into the plug-in collection.
| Column | Description |
|---|---|
| c001 | An item name implementing the plug-in. |
| c002 | Must eual LOAD. |
| c003 | Page request used to load a page. |
| n003 | An internal APEX process ID. |
Translation Messages
The plug-in supports the following Oracle APEX Text Messages. The translation Text message must be defined in an application, and it has to have the attribute Used in JavaScript enabled.
| Translation Code | Translation default text |
|---|---|
| UC_CONFIRM_UPLOAD_PENDING | File(s) are not yet uploaded. Do you want to continue? |
Validation
The plug-in supports HTML5 validation using an item attribute Validation and PL/SQL validation checking if rich text HTML is empty. Additionally, the plug-in has built-in validation checking if the currently edited CLOB value has been changed before submitting a page.
Understanding CLOB checksum validation
When the page is submitted, the built-in plug-in validation compares the on-load CLOB checksum with the CLOB checksum stored in the database. If the on-load CLOB checksum differs from the CLOB checksum stored in the database, then the page submission is terminated with the error message “Value has been overridden in the meantime. Reload the page and save it again”.
The purpose of this feature is the following:
- prevent two different end-users from saving their changes to the same CLOB stored in the database,
- prevent one end-user from saving different changes done in multiple browser tabs on the same CLOB.
This requires comparing the on-load CLOB checksum with the CLOB checksum currently stored in the database. When a page is submitted, the plug-in calculates the CLOB checksum stored in the database and compares it against the checksum calculated when the plug-in was rendered.
Additionally, the developer can disable this feature or can restrict which page submission requests should be used to perform the plug-in built-in CLOB checksum validation.
By default the plug-in uses APEX hidden item f01 to store CLOB checksum. The checksum can be automatically stored in APEX page item, when page item PX_ITEMNAME_CHECKSUM is defined on page, where PX_ITEMNAME is page item name used to implement the plug-in.