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.addValue is 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-in
• apexdarefresh - 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-in
• apexdarefresh - an item is refreshed by the native Refresh dynamic action

---

Session State

The plug-in implements it's own session state using APEX collections and monitors/relies on APEX page item session state. It allows the plug-in handling CLOB values across APEX versions starting with Oracle APEX 19.2.

VARCHAR2 limitation

In Oracle APEX prior 22.2 all page items values are stored in APEX Session State as VARCHAR2 values. Setting APEX page item session state to value exceeding the limitation results in assigning NULL value which prohibits developers from updating CLOB values in the database. On the other hand attempts to load values exceeding the VARCHAR2 limitation results in raising PL/SQL errror: ORA-06502: PL/SQL: numeric or value error.

The VARCHAR2 limitation for Oracle APEX page items was resolved with Oracle APEX 22.2 introducing CLOB handling on APEX session state.

Rich Text Editor Pro solution

The plug-in resolved the problem of VARCHAR2 limitation starting with Oracle APEX 19.2. The plug-in allows CLOB handling using the plug-in PL/SQL API or the supporting process plug-in.

Oracle APEX 19.2 onwards

Rich text documents exceeding VARCHAR2 limitation can be loaded and updated using the supporting process plug-in and the plug-in PL/SQL API. A page item session state must be evaluated using the plug-in PL/SQL API:

• to clear page item session state using APEX URL use the plug-in procedure UC_FROALA.manageClearCache
• to get page item session state use the plug-in function UC_FROALA.getValue
• to set page item session state use the plug-in procedure or function UC_FROALA.setValue

Oracle APEX 22.2 onwards

When native CLOB support is available, the plug-in can load and update CLOB values in the database using the native Oracle APEX components without any additional adjustments. The plug-in handles page item session state relying on native Oracle APEX CLOB support.

Plug-in session state

The plug-in uses APEX collection UC_FROALA to handle session state of currently edited rich text document. The collection is created for all plug-in instances across all application pages and it stores the following information about rich text document created using the plug-in:

• rich text document HTML as CLOB value
• images added or removed from a rich text document
• classes applied using application builder page designer
• APEX processes meta-data used to load CLOB value

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 a page item name implementing the plug-in, and column c002 describe what kind of information is stored in a row. The following values are used for column c002 :

• ONLOAD - rich text document HTML laoded when page was loading (on-laod CLOB)
• DRAFT - rich text document HTML currently stored in the plug-in session state (draft CLOB)
• IMAGE - an image metadata detected in rich text document HTML
• CLASS - page item classes defined using page item attribute Advanced \ CSS Classes
• LOAD - an APEX process implementing supporting process plug-in used to load CLOB value from the database

On-load CLOB in plug-in collection

The on-load CLOB is stored in the plug-in collection when

• the supporting process plug-in is used to load CLOB value from the database.
• the plug-in PL/SQL API is used to load CLOB value from the database
• a page item implementing the plug-in is rendered

The on-load CLOB is used by the plug-in validation procedure checking if the rich text document wasn't altered by other end-user since it was loaded to the rich text editor.

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 checksum of CLOB value
n002	The lenth of CLOB value
clob001	The rich text document HTML stored as CLOB

Draft CLOB in plug-in collection

The draft CLOB is stored in the plug-in collection when:

• the supporting process plug-in loads CLOB value from the database
• the plug-in PL/SQL API is used to load CLOB value from the databe
• the plug-in is rendered on page load
• the supporting dynamic action Update CLOB is triggered
• the page implementing the plug-in is submitted

This CLOB value is used to update value in the database on page submission using the supporting process plug-in or the plug-in PL/SQL API.

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

Referencing page item value in Oracle APEX 22.2 onwards

It's recommended that for Oracle APEX 22.2 onwards, a page item current value should be referenced using native methods, for example bind variables or the native Oracle APEX PL/SQL API.

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 (or when the supporting process plug-in is used to load CLOB from the database). Both have the same value, length, and checksum. The on-load CLOB value is preserved until the next page load so it can be used to perform CLOB checksum validation on page submission. On the other hand, the draft CLOB is updated whenever

• a supporting dynamic action Update CLOB is triggered
• a page implementing the plug-in is submitted
• the plug-in PL/SQL API setting plug-in session state is executed

About CLOB checksum validation

See section Validation \ Understanding CLOB checksum validation to learn more about the built-in plug-in validation.

Images

Whenever images in rich text document are added, updated or removed, the plug-in updates it's session state storing the most recent information about images. The plug-in tracks all image changes, allowing maintaining images in the database.

The table below presents an image meta-data stored in the plug-in session state:

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 or N indicating whether an image was embedded in rich text document when the plug-in was initialized
c005	Flag Y or N indicating whether an image was added to rich text document after the plug-in was initialized
c006	Flag Y or N indicating whether an image was removed from rich text HTML after the plug-in was initialized
c007	Flag Y or N indicating whether an image is a base64 image
c008	Flag Y or N indicating whether an image is uploaded using the plug-in RESTful service
c009	Flag Y or N indicating whether an image can be safely removed from the database on page submission [1]
c010	An image current URL [2]
c011	An image's current ID stored in the database [3]

Annotations

• [1] - An uploaded image can be safely removed from the database when an image URL is not shared with other images
• [2] - available only for non-base64 images
• [3] - available only for images uplaoded using the plug-in

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.

Known Issues

Item source

Despite the introduction of CLOB support in Oracle APEX 22.2, using the page item source attribute to load a CLOB value can cause PL/SQL 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) but in reality, they raise an error at the APEX engine level, which is beyond the plug-in's control.

---

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 currently stored in the database. If checksums don't match, the page submission is terminated with error message:

Value has been overridden in the meantime. Reload the page and save it again

The purpose of this feature is the following:

1. prevent two different end-users from saving their changes to the same CLOB stored in the database,
2. prevent one end-user from saving different changes done in multiple browser tabs on the same CLOB.

A developer can enable CLOB checksum validation using the plug-in page item attribute Validation Request(s).

By the default the plug-in uses APEX hidden items named f01 to store page items CLOB checksums. A page item checksum can be stored in a custom page item - just create a new page item named {PX_PAGE_ITEM}_CHECKSUM, where {PX_PAGE_ITEM} is page item implementing the plug-in.