Plug-in 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. This documents covers the plug-in session state implemented using Oracle APEX collections.
Oracle APEX limitations unleashed
Before Oracle APEX 22.2 page item value is stored in APEX session state using VARCHAR2, which implicts page item maximum value of 32 767 characters. Setting a page item value exceeding the limitation results in assigning NULL value. On the other hand loading values exceeding the VARCHAR2 limitation into page item session state results in raising PL/SQL errror: ORA-06502: PL/SQL: numeric or value error.
Rich Text Editor Pro enables handling CLOB values for Oracle APEX 19.2 using the supporting process plug-in and the plug-in PL/SQL API. When the plug-in is implemented in Oracle APEX 22.2 onwards, the plug-in relays on the native session state and no additional adjustments are required.
Plug-in session state
Rich Text Editor Pro uses Oracle APEX collection UC_FROALA to handle session state of currently edited rich text document. The collection is used by all plug-in instances across application pages and it stores the following information about rich text documents:
- rich text document HTML as CLOB value
- images added or removed from a rich text document (including image meta data)
- classes applied using application builder page designer
- APEX processes meta-data used to load
CLOBvalue - Initialization PL/SQL variables
The plug-in collection uses columns c001 and c002 to identify which plug-in instance meta-data is stored in the collection row.
| Column | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | Page item name for which collection row is created. |
| C002 | VARCHAR2 | Describes what information is stored in the collection row. |
The column c002 can have values described in the table below.
| Value | Description |
|---|---|
| ONLOAD | The collection row contains information about on-load CLOB value loaded when the plug-in was rendered by Oracle APEX. |
| DRAFT | The collection row contains information about draft CLOB value currently stored in the plug-in session state. |
| IMAGE | The collection row describe an image added or removed to/from rich text document.. |
| CLASS | The collection row describes classes added to a page item using page designer Advanced \ CSS Classes attribute |
| LOAD | The collection row describes a page process implementing the supporting process plug-in to load CLOB value. |
| VAR | The collection row describes the plug-in PL/SQL variables values assigned when the plug-in was rendered. |
Learn more about each collection row column usage in the section The plug-in collection.
Get document CLOB value
- Oracle APEX 19.2+
- Oracle APEX 22.2+
The currently edited document can be fetched from the plug-in session state using the plug-in PL/SQL function getValue.
Getting a page item value from APEX session state should be fetched using APEX native methods, for example using bind variables or native APEX PL/SQL API.
Set document CLOB value
- Oracle APEX 19.2+
- Oracle APEX 22.2+
The current document in the plug-in session state can be set using the plug-in PL/SQL procedure setValue
Setting a page item value in APEX session state should be set using APEX native methods, for example using bind variables or native APEX PL/SQL API.
The plug-in collection
On-load CLOB
The on-load CLOB is used by the plug-in validation procedure checking (executed on page submission) if currently edited rich text document wasn't altered in the database by other user since it was loaded to the rich text editor.
This rich text document CLOB value is created in the plug-in session state when:
- the supporting process plug-in is used to load CLOB value from the database on page load.
- the plug-in PL/SQL API is used to load CLOB value from the database on page load
- a page item implementing the plug-in is rendered by Oracle APEX (plug-in checks whether supporting process plug-in or PL/SQL API was used to load a value)
The plug-in session state for on-load CLOB is described by the plug-in collection row described in the table below.
| Column | Type | Value description |
|---|---|---|
| C001 | VARCHAR2 | A page item name implementing the plug-in. |
| C002 | VARCHAR2 | Always set to ONLOAD. |
| N001 | NUMBER | The checksum of CLOB value calculated by the plug-in. |
| N002 | NUMBER | The length of CLOB value in bytes. |
| CLOB001 | CLOB | The rich text document HTML |
Learn more about the plug-in checksum validation in Rich Text Editor Pro \ Plug-in: Page item \ Oracle APEX integration \ Validation
Draft CLOB
The draft CLOB is used by the plug-in to reflect the current value of rich text document in the plug-in session state. This value is used to update CLOB value in the database on page submission when using the supporting process plug-in or the plug-in PL/SQL API.
The CLOB value is stored in the plug-in session state when:
- the supporting process plug-in is used to load CLOB value from the database on page load.
- the plug-in PL/SQL API is used to load CLOB value from the database on page load
- a page item implementing the plug-in is rendered by Oracle APEX (plug-in checks whether supporting process plug-in or PL/SQL API was used to load a value)
- the supporting dynamic action Update CLOB is executed
- a page implementing the plug-in is submitted
The plug-in session state for draft CLOB is described by the plug-in collection row described in the table below.
| Column | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | An item name implementing the plug-in |
| C002 | VARCHAR2 | Always set to DRAFT |
| N001 | NUMBER | The checksum of CLOB value calculated by the plug-in. |
| N002 | NUMBER | The length of CLOB value in bytes. |
| CLOB001 | CLOB | The rich text document HTML |
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 plug-in sample application includes live example of images in the plug-in session state. Click here to open to the plug-in live demo for images in the plug-in session state.
The table below presents an image meta-data stored in the plug-in session state:
| Column | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | An item name implementing the plug-in |
| C002 | VARCHAR2 | Must equal IMAGE |
| C003 | VARCHAR2 | An unique image ID assigned by the plug-in, for example, ui-id-1 |
| C004 | VARCHAR2 | Flag Y or N indicating whether an image was embedded in rich text document when the plug-in was initialized |
| C005 | VARCHAR2 | Flag Y or N indicating whether an image was added to rich text document after the plug-in was initialized |
| C006 | VARCHAR2 | Flag Y or N indicating whether an image was removed from rich text HTML after the plug-in was initialized |
| C007 | VARCHAR2 | Flag Y or N indicating whether an image is a base64 image |
| C008 | VARCHAR2 | Flag Y or N indicating whether an image is uploaded using the plug-in RESTful service |
| C009 | VARCHAR2 | Flag Y or N indicating whether an image can be safely removed from the database on page submission. An uploaded image can be safely removed from the database when an image URL is not shared with other images |
| C010 | VARCHAR2 | An image current URL. An image URL is available only for non-base64 images (uploaded using RESTful service or added manually via URL) |
| C011 | VARCHAR2 | An image's current ID stored in the database - 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 | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | An item name implementing the plug-in. |
| C002 | VARCHAR2 | Must eual CLASS. |
| C010 | VARCHAR2 | 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 | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | An item name implementing the plug-in. |
| C002 | VARCHAR2 | Must eual LOAD. |
| C003 | VARCHAR2 | Page request used to load a page. |
| C003 | VARCHAR2 | An internal APEX process ID. |
PL/SQL Variables
The table below presents the collection columns describing initialization PL/SQL variables used by the plug-in.
| Column | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | An item name implementing the plug-in. |
| C002 | VARCHAR2 | Must eual VAR. |
| C003 | VARCHAR2 | Variable name |
| C004 | VARCHAR2 | Variable type |
| C005 | VARCHAR2 | Variable value |
Learn more about plug-in variables in Rich Text Editor Pro \ Database objects \ Packages \ UC_FROALA_RTE
Toolbar PL/SQL definition
The table below presents the collection columns describing toolbar definition set using the plug-in PL/SQL API toolbar_init_group.
| Column | Type | Description |
|---|---|---|
| C001 | VARCHAR2 | An item name implementing the plug-in. |
| C002 | VARCHAR2 | Must eual TOOLBAR. |
| C003 | VARCHAR2 | The toolbar responsive threshold [1] |
| C004 | VARCHAR2 | The toolbar group [2] |
| C005 | VARCHAR2 | The number of visible buttons in given group |
| C006 | VARCHAR2 | The group alignment in the toolbar |
| C007 | VARCHAR2 | The group button ids separated with comma |
- [1] The value reflects the plug-in package constants c_toolbar_responsive_sd, c_toolbar_responsive_md, c_toolbar_responsive_sm and c_toolbar_responsive_xs
- [2] The value reflects the plug-in package constants c_toolbar_group_paragraph, c_toolbar_group_text, c_toolbar_group_rich, c_toolbar_group_misc
Other topics
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
Learn more about the plug-in checksum validation in Rich Text Editor Pro \ Plug-in: Page item \ Oracle APEX integration \ Validation
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.