Table of Contents

Features at a Glance

Supports CLOB Values

Unleash the full potential of the Froala WYSWIG editor for Oracle APEX. The plug-in implements its own CLOB handling, so you don’t have to bother with Oracle APEX session state limitation to 32 767 characters.

Easy CLOB Handling

The plug-in is delivered with an additional process plug-in which simplifies CLOB handling. You can easily load and update CLOB content using a SQL Query, Function Body, Named Table or our PL/SQL API.

Advanced Image Editing

Integrates with the TUI Image Editor, a 3rd party library, which allows end-users to manipulate images in the Froala editor.

Right to Left Support

The Froala editor features RTL support based on the applied language or it can be initiated manually using the plug-in attributes and supporting dynamic action plug-in.

Highly Customizable

The Froala editor can be customized through item attributes or using the supporting dynamic action plug-in.

RESTful Enabled

The plug-in integrates with RESTful services in order to handle image uploading.

Uploading images to APEX collection

Images are uploaded to the APEX collection and can be saved on-page submission using the supporting process plug-in.

Requirements

The Plug-in

The Froala Editor

Introduction

The Froala Editor is a lightweight WYSIWYG HTML editor written in JavaScript that enables rich text editing capabilities for your applications. It's beautiful, easy to integrate for developers, and your users will simply fall in love with its clean design. We think Froala is the perfect addition to Oracle APEX - making HTML editing easy and aesthetically pleasing.

Simple.

Lots of features don't have to overwhelm the user with hundreds of buttons. Froala's WYSIWYG editor smart toolbar can accommodate over 100 features in a simple interface.

Smart. Intuitive.

The Froala Smart Toolbar groups all actions, by scope, into 4 categories. It's an intuitive toolbar where every feature is easy to find and your most used ones are there for you.

Full of features.

Froala Rich Text Editor has a vast range of both simple and complex features for all kinds of use cases.

Out of the box extensions.

There's no need to reinvent the wheel. This rich text editor comes with over 30 out of the box extensions to choose from and use in your project.

Visit Froala's website to find out more.

Languages

The Froala editor supports 38 languages out of the box:

• Arabic

• Bosnian

• Czech

• Danis

• German

• Greek

• English Canada

• English United Kingdom

• English United States

• Estonian

• Spanish

• Persian

• Finnish

• French

• Hebrew

• Croatian

• Hungarian

• Indonesian

• Italian

• Japanese

• Korean

• Kurdish

• Montenegrin

• Norwegian

• Dutch

• Polish

• Portuguese Brazil

• Portuguese Portugal

• Romanian

• Russian

• Serbian

• Slovak

• Swedish

• Thai

• Turkish

• Ukrainian

• Vietnamese

• Chinese China

• Chinese Taiwan

The Plug-in Implementation

The plug-in implements the Froala editor using the Froala API options, events, and methods.

Toolbar

The plug-in implements the toolbar buttons using the Froala toolbar groups: Paragraph, Text, Rich, and Misc. Each group contains a set of Froala buttons and the number of buttons varies depending on the selected toolbar preset: basic, intermediate, or full.

The plug-in allows easy toolbar customization through:

• APEX item attributes \ Advanced \ JavaScript Initialization Code

• dynamic action \ the supporting plug-in

The plug-in by default implements the following buttons

Toast UI Image Editor

The Froala editor supports 3rd a party library allowing image manipulation directly in the browser. Learn more at https://ui.toast.com/tui-image-editor .

Standard Attributes

The plug-in implements the following standard APEX plug-in attributes:

• Is Visible Widget

• Standard Form Element

• Has Element Attributes

• Has Placeholder Attribute

• Session State Changeable

• Has Source Attributes

• Has “Initialization JavaScript Code” Attribute

• Has Read Only Attribute

Custom Attributes

Application

The plug-in exposes 3 application attributes in order to have a common configuration for all the plug-in instances across all pages. These attributes define URLs to RESTful services handling images (browsing, uploading, and deleting).

Component

The plug-in exposes 8 component attributes that are defined at the item level.

	Attribute	Type	Dependent on	Description
1	Settings	Checkbox Enable Browser Built-in Spell Check Enable Sticky Toolbar Enable TUI Image Editor Override Application Attributes Validate CLOB Checksum on Page Submit	-	Enable Browser Built-in Spell Check when checked - built-in browser spell check is enabled for the Froala editor when not checked - built-in browser spell check is disabled for the Froala editor Enable Sticky Toolbar when checked - the Froala toolbar is frozen when the end-user scrolls the page. The top offset of the toolbar can be set using the Toolbar Top Offset attribute when not checked - the Froala toolbar top position is not affected when the end-user scrolls the page Enable TUI Image Editor when checked - the Froala editor is enabled with 3rd party library TUI Image Editor. This allows end-users to edit images directly in an application. Edited images are re-uploaded or re-embedded depending on the Embed Images as Inline Base64 setting. when not checked - the Froala editor doesn’t include the TUI Image Editor. Override Application Attributes when checked - application attributes can be overridden on an item level using the plug-in component attributes. See the Image Upload URL, Image Browse URL, and Image Delete URL attributes of an item. when not checked - application attributes defining the plug-in’s image handling RESTful URLs are used. See the plug-in component settings to view the currently used URLs. Validate CLOB Checksum on Page Submit when checked - the plug-in performs built-in validation on the CLOBs each time the page is submitted. Additionally, the submit request can be specified to restrict the validation to given requests. See the Validation Request(s) attribute of an item. when not checked - the plug-in doesn’t perform built-in validation on the CLOBs.
2	Validation Request(s)	Text	Settings Validate CLOB Checksum On Page Submit is checked	Use this attribute to restrict the plug-in built-in validation to the given comma-separated list of requests. Leaving this attribute blank will execute built-in validation on each page submission.
3	Toolbar	Select list Basic Intermediate Full	-	Defines what toolbar preset is applied to the Froala editor
4	Toolbar Top Offset	Number	Settings Enable Sticky Toolbar is checked	When the Froala Toolbar is set to be sticky, the top offset can be set using this attribute. Default value is 48px which is the default height of Universal Theme header bar in the page template.
5	Height	Number	-	This attribute allows you to set height (in pixels) of the editor. The given value is used to set the height property. Keep in mind the height doesn't include toolbar and the footer of the editor - it is only applied to working area.
6	Upload Image(s) on Request(s)	Text	-	Attribute accepts comma separated APEX page submission requests. When specified, the plug-in uploads images only for the given requests. Otherwise, images remains in CLOB content as they were embeded and are not uploaded using plug-in REST on page submission.
7	Image Upload URL	Text	Settings Override Application Attributes is checked	To learn more, read the description for the attribute in the section Application above. Attribute value overrides the application scope of the plug-in settings for the selected item.
8	Image Browse URL	Text	Settings Override Application Attributes is checked	To learn more, read the description for the attribute in the section Application above. Attribute value overrides the application scope of the plug-in settings for the selected item.
9	Image Delete URL	Text	Settings Override Application Attributes is checked	To learn more, read the description for the attribute in the section Application above. Attribute value overrides the application scope of the plug-in settings for the selected item.
10	Image GET URL	Text	Settings Override Application Attributes is checked	To learn more, read the description for the attribute in the section Application above. Attribute value overrides the application scope of the plug-in settings for the selected item.

Events

The plug-in exposes events that can be bound using APEX dynamic actions.

Change (native)

The plug-in triggers a native change event (change) without any additional event data. The event is triggered by the plug-in when:

• dynamic action Refresh AJAX request is finished

• the end-user leaves the Froala editor after changing the CLOB content

• APEX JavaScript API apex.item.addValue is executed

Before Refresh (native)

The plug-in triggers a native before refresh event (apexbeforerefresh) before an item is refreshed using a native dynamic action Refresh and before the plug-in is reset to ONLOAD CLOB using the supporting plug-in United Codes Rich Text Editor Pro (Extend) \ Reset value.

After Refresh (native)

The plug-in triggers a native after refresh event (apexafterrefresh) after an item is refreshed using a native dynamic action Refresh and after the CLOB content is reset to ONLOAD CLOB using the supporting plug-in United Codes Rich Text Editor Pro (Extend) \ Reset value.

UC Froala CLOB updated

The plug-in triggers the event (ucfroalaclobdraftupdated) after the DRAFT CLOB is updated in the plug-in collection.

UC Froala CLOB reset

The plug-in triggers the event (ucfroalaclobonloadreset) after the Froala editor content is reset to ONLOAD CLOB.

UC Froala Option Changed

The plug-in triggers the event (ucfroalaoptionchanged) after executing the following United Codes Rich Text Editor Pro (Extend) actions:

• Disable Base64 Images

• Enable Base64 Images

• Image Browser Parameters

• Upload Parameters

The event is triggered along with this.data object described below

UC Froala Before Initialization

The plug-in triggers the event (ucfroalabeforeinitialize) in order to extend the Froala configuration with dynamic actions which implement the United Codes Rich Text Editor Pro (Extend) supporting plug-in. The event can be used on the APEX global page to change the settings of all plug-in instances across all pages in an application.

The event is triggered along with this.data JSON object described below

UC Froala Initialized

The plug-in triggers the event (ucfroalacontentinitialized) right after the Froala editor is created.

The event is triggered along with this.data JSON object described below

UC Froala Content Changed

The plug-in event (ucfroalacontentchanged) is triggered when content within the Froala editor changes.

The event is triggered along with this.data JSON object described below

UC Froala Image Browser Error

The plug-in event (ucfroalaimagemanagererror) is triggered when the Froala Image Manager (image browser) raises an error.

The event is triggered along with this.data JSON object described below

UC Froala Image Upload Error

The plug-in event (ucfroalaimageuploaderror) is triggered when image upload fails.

The event is triggered along with the this.data JSON object described below

UC Froala Images In Collection

The plug-in event (ucfroalacollectionimageschanged) is triggered after:

• an image is added to the Froala editor

• an image is removed from the Froala editor

• the plug-in is initialized on page load

The event is triggered along with this.data JSON object. It contains 2 arrays of JSON objects: added and removed. Each image entry is described as in table below:

PL/SQL API

The plug-in exposes a PL/SQL API which can be used in custom development.

access_token_validate

The function is used by the RESTful services to validate the access token. Learn more about RESTful services and access token in the plug-in documentation (RESTful Image Handling).

The procedure is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
function access_token_validate (   
p_access_token in varchar2   
) return boolean;
...
end UC_FROALA_RTE;

manageClearCache

In order to imitate native APEX behavior, the plug-in is delivered with a manageClearCache procedure which clears the CLOBs used by the plug-in when clearing items via URL syntax. The procedure interprets friendly URLs and old-style URLs. The procedure has to be implemented manually as an application process (Shared Components \ Application Processes) with the execution point set to On Load: Before Header (page template header).

The procedure is defined in the UC_FROALA_RTE package and doesn’t accept any arguments.

create or replace package UC_FROALA_RTE as
...
procedure manageClearCache;
...
end UC_FROALA_RTE;

Application process code has to be set to

UC_FROALA_RTE.manageClearCache;

clear

The procedure accepts only one argument which is the APEX item name implementing the plug-in. The procedure removes all collection rows describing the given item.

The procedure is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
procedure clear(
p_item_name in varchar2
);
...
end UC_FROALA_RTE;

clobDisplay

The procedure accepts only one argument which is CLOB content saved using the plug-in. The procedure renders two required CSS files and displays CLOB HTML.

The procedure is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
procedure clobDisplay(
p_clob in clob
);
...
end UC_FROALA_RTE;

clobGetHTML

The function accepts two arguments. The first is the CLOB content saved using the plug-in, and second the boolean flag indicating whether plug-in CSS files will be added or not. Function returns modified CLOB which has to be display manualy by a developer.

The function is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
function clobGetHTML(
p_clob        in clob,
p_include_css in boolean default false
) return clob;
...
end UC_FROALA_RTE;

getChecksum

The function accepts only CLOB and returns a calculated checksum.

The function is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
function getChecksum(
p_clob IN CLOB
) return number;     
...
end UC_FROALA_RTE;

getValue

The function accepts only one argument which is the APEX item name implementing the plug-in. It fetches the DRAFT CLOB from the APEX collection and returns its content.

The function specification is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...

function getValue(   
p_item_name in VARCHAR2 default g_item.name   
) return CLOB;

...
end UC_FROALA_RTE;

setValue #1

The function sets the plug-in session state (collection) and the APEX session state (an item value). The function does the following:

1. set ONLOAD CLOB

2. set DRAFT CLOB

3. set an item session state to the given CLOB checksum

4. return the given CLOB checksum

The function specification is defined in the the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...

function setValue(   
p_item_name   in varchar2,   
p_value       in CLOB   
) return varchar2;   

...
end UC_FROALA_RTE;

setValue #2

The function sets the plug-in collection CLOB to ONLOAD or DRAFT. It allows developers to decide whether to set the given APEX item session state. As a result, it returns a checksum of the CLOB stored in the plug-in collection.

Read the description of the arguments below to learn details.

The function specification is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
function setValue( 
p_item_name   in varchar2 default g_item.name, 
p_type        in varchar2, 
p_value       in CLOB, 
p_set_session in boolean default true 
) return varchar2;
...
end UC_FROALA_RTE;

setValue #3

The procedure sets the plug-in session state (collection) and the APEX session state (an item value). The procedure does the following:

1. set ONLOAD CLOB

2. set DRAFT CLOB

3. set an item session state to the given CLOB checksum

The procedure specification is defined in the UC_FROALA_RTE package.

create or replace package UC_FROALA_RTE as
...
procedure setValue(   
p_item_name   in varchar2,   
p_value       in CLOB   
);
...
end UC_FROALA_RTE;

Images

Images can be added to the Froala editor in different ways:

• Froala built-in image selection,

• drag and drop images from desktop,

• copy and paste content from clipboard.

In most cases images are added as base64 images and they are uploaded on page submission depending on the plug-in configuration (See plug-in attribute Upload Images on Requests).

When images are added using Froala built-in image selection box or using drag and drop they are being converted to base64 images. When images are added with paste command they are added diffrently depending what is stored in clipboard content. If image is pasted with external URL then it will be downloaded by the plug-in and uploaded on page submission. There is the possibility a server hosting an image doesn’t allow fetching image over AJAX call and this image will remain in CLOB content with URL as it was in clipboard.

Removing images

When an image is removed from the editor, the plug-in remembers its state in the plug-in collection. If an image was already uploaded by the plug-in REST module it can be deleted on page submission using the supporting process plug-in action Delete Removed Images.

APEX Integration

The plug-in integrates with Oracle APEX through the APEX JavaScript API, the plug-in API, and item attributes.

Item Session State

Oracle APEX session state only handles item values up to 32 767 characters long. Values exceeding this limitation are changed to NULL, thus it is impossible to properly handle native Oracle APEX Rich Text Editor items exceeding the limitation. This APEX behavior affects all APEX item types including plug-ins.

Because of this, the plug-in uses its own session handling which is based on the APEX collection CLOB column. The APEX session state for an item implementing the plug-in is for informative purposes and for internal plug-in usage.

APEX Item Session State

An APEX item implementing the plug-in can have a value set to NULL or VARCHAR2.

NULL

The NULL value is assigned

• on page load- the collection stores an empty CLOB or the collection is not yet initialized,

• on page submission - the Froala editor is empty

The NULL value is assigned in order to allow developers to create simple APEX validations such as ITEM IS NOT NULL.

VARCHAR2

A VARCHAR2 value is assigned

• on page load - the collection stores a not-null ONLOAD or DRAFT CLOB

• on page submission - the Froala editor is not empty

Additionally, the VARCHAR2 value follows the syntax “X:Y”, where

• X is ONLOAD CLOB checksum

• Y is DRAFT CLOB checksum

When X or Y is equal to 0 it means the specific CLOB is (or was) empty.

The VARCHAR2 value is used by the plug-in to execute built-in CLOB checksum validation.

Native APEX Validations

Because the plug-in supports CLOB values (APEX changes CLOB value into NULL), the majority of native APEX validations have no use with the plug-in. Despite that, as it is described in APEX integration \ Item Session State, the plug-in takes advantage of the APEX Item Session State to indicate whether an item implementing the plug-in is NULL or NOT NULL.

This behavior should be used along with the Item is NOT NULL native APEX validation. For other cases where a CLOB value has to be parsed, it is recommended to use validations that allows custom PL/SQL code where the developer can use the plug-in API to fetch the CLOB content.

Support for CLOB Values

The plug-in does not rely on the APEX item session state, instead, it uses an Oracle APEX collection to handle CLOB values for the Froala editor. The plug-in uses a collection called UC_FROALA (common for all instances created in an application). It is important to understand the information stored in the collection in order to understand how the plug-in handles CLOBs.

The plug-in uses several collection columns to maintain the state of Froala editor. These columns are used to describe:

1. CLOB (ONLOAD) state on page load (collection column c002 = 'ONLOAD')

2. CLOB (DRAFT) state after page submission or after updating the CLOB using the the supporting dynamic action plug-in action Update CLOB (collection column c002 = 'DRAFT')

3. added or removed images using the Froala editor plug-in (collection column c002 = 'IMAGE')

4. assigned classes to the plug-in instance in APEX page designer (collection column c002 = 'CLASS')

5. processes implementing supporting process plug-in to load CLOB content (collection column c002 = 'LOAD')

Onload CLOB

Draft CLOB

Images

Classes

Processes

Difference Between ONLOAD CLOB and DRAFT CLOB

Both ONLOAD and DRAFT CLOBs are created when the plug-in is being rendered. After page load, both CLOBs have the same checksum and length. The ONLOAD CLOB checksum is used to perform the plug-in checksum validation when the page is submitted. When the end-user changes the content of CLOB it doesn’t automatically update the DRAFT CLOB. The DRAFT CLOB is updated only when the page is submitted or on-demand using the supporting dynamic action plug-in (United Codes Rich Text Editor Pro (Extend) / Settings / Execute / Update CLOB).

Understanding CLOB Checksum Validation on Page Submission

When the page is submitted, the plug-in built-in validation compares the CLOB checksum (ONLOAD) with the CLOB checksum stored in the database. If the 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 to:

1. prevent two different end-users from saving their changes to the same CLOB stored in the database,

2. prevent the one end-user from saving different changes done in multiple browser tabs on the same CLOB.

This requires comparing the ONLOAD CLOB checksum (created when the plug-in is rendered) with the checksum of the CLOB currently stored in the database. When the page is submitted the plug-in has access to the ONLOAD checksum but it has to fetch the current checksum of the CLOB stored in the database. Because of this, the CLOB has to be loaded using the United Codes Rich Text Editor Pro (Process) supporting plug-in or by using the item attribute Source \ SQL Query. Loading a CLOB using the plug-in API or using the native APEX process won’t allow the plug-in to dynamically fetch the CLOB on page submission in order to compare checksums.

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.

Item Attribute Integration

Appearance

Validation

Advanced

function( pOptions ) {
return pOptions;
}

Source

The item source attribute is supported and the plug-in mimics native Session State handling.

Default

Not supported - might be supported in a future release.

Read Only

The plug-in supports the read-only attribute. When read-only mode is active then the plug-in renders the required HTML code to render the CLOB content.

Dynamic Action integration

APEX Item JavaScript Integration

Help in the Application Builder

The plug-in provides built-in help text for all of the plug-in attributes in APEX Page Designer.

Supporting Plug-ins

The plug-in is delivered with two supporting plug-ins, United Codes Rich Text Editor Pro (Extend) and United Codes Rich Text Editor Pro (Process). The purpose of these plug-ins is to simplify the handling of CLOB state and to extend the plug-in with additional functionality.

United Codes Rich Text Editor Pro (Process)

This is a process plug-in enabling the developer to clear, load, and update CLOB content in a convenient way. Depending on the selected type different attributes are exposed. Use of this plug-in is required to enable built-in CLOB checksum validation.

The plug-in exposes 4 actions:

• Clear CLOB

• Load CLOB

• Update CLOB

• Delete Removed Images

Clear CLOB

Clears the plug-in collection state and sets the item’s APEX Session State to NULL. It should be used as an equivalent for the native Clear process.

After creating the process implementing the supporting plug-in and setting the Action to Clear CLOB, the developer has to provide two attributes:

Clear CLOB can be used both on pre-rendering (Before Header, After Header, and Before Regions) and after page submission (Processing and After Processing).

Load CLOB (SQL Query)

This action should be used to load the CLOB value into the plug-in item. After creating the process which implements the supporting plug-in and setting the Type to Load CLOB (SQL Query), the developer has to provide two attributes:

select
CLOB_CONTENT
from 
UC_RTE_CLOBS 
where 
id = :P4_ID;

Load CLOB (Function Body Returning CLOB)

This action should be used to load the CLOB value into the plug-in item. After creating the process which implements the supporting plug-in and setting the Type to Load CLOB (Function Body Returning CLOB), the developer has to provide two attributes:

declare
v_clob clob;
v_result clob;
v_test number;
begin
if :P4_ID is null then 
v_result := to_clob(null);
else
select
  CLOB_CONTENT
into
  v_result
from 
  UC_RTE_CLOBS
where 
  id = :P4_ID
;
end if;

return v_result;
end;

Load CLOB (Table)

This action should be used to load the CLOB value into the plug-in item. After creating the process which implements the supporting plug-in and setting the Type to Load CLOB (Table), the developer has to provide six attributes:

Update CLOB (PL/SQL Code)

This action should be used to update the CLOB content stored in the database after the page is submitted. It allows a developer to write a custom update statement wrapped as anonymous PL/SQL Code. The attribute supports the CONTENT bind variable which references the submitted CLOB value.

After creating the APEX process which implements the supporting plug-in a developer has to set the Settings \ Type attribute to Update CLOB (PL/SQL Code) and set 2 attributes described in the table below.

update 
#OWNER#.UC_RTE_CLOBS
set
CLOB_CONTENT = :CONTENT
where
ID = :P4_ID;

UC_FROALA_RTE.g_froala_sqlrowcount := SQL%ROWCOUNT;

Update CLOB (Table)

This action should be used to update the CLOB content stored in the database after the page is submitted. It allows a developer to supply a schema, table, CLOB column, PK column(s) and Item(s) with PK values.

After creating the APEX process which implements the supporting plug-in a developer has to set the Settings \ Type attribute to Update CLOB (Table) and set the attributes described in the table below.

Delete Removed Images

When the plug-in is initialized along with CLOB containg images, it stores images informations (URLs and IDs) in the plug-in collection UC_FROALA. When end-user removes existing image, the plug-in updates collection and changes an image status to removed.

When process Delete Removed Images is executed, the code defined in attribute PL/SQL Code is executed in the loop over removed images. Use the plug-in variable UC_FROALA_RTE.g_froala_image_id to reference an image database ID and UC_FROALA_RTE.g_froala_image_get_url to reference an image get URL.

You can also check flag UC_FROALA_RTE.g_froala_image_safe_to_delete indicating whether an image (uploaded using plug-in REST) can be safely deleted in database (in the context of processed CLOB). An image can be safely removed only when not removed images are not using exactly the same URL. Images can share URL within same CLOB when an image is copied and pasted by the end-user using the Froala editor.

declare
v_removed_img_id number := UC_FROALA_RTE.g_froala_image_id;
begin
delete from UC_FROALA_SAMPLE_BLOBS where id = v_removed_img_id;
end;  

United Codes Rich Text Editor Pro (Extend)

A dynamic action plug-in which extend the Froala editor configuration (toolbar customization and the plug-in settings). It also allows updating the DRAFT CLOB without submitting the page and resetting the CLOB value to the ONLOAD CLOB.

Change Toolbar

The Change Toolbar settings can be applied to the Froala editor before it is initialized by the plug-in. This means these actions have to be set on event UC Froala Before Initialization. The plug-in doesn’t restrict the number of true (or false) actions - multiple true (or false) actions can be used in one dynamic action.

Change Settings

The Change Settings action can be applied to the Froala editor only before it is initialized by the plug-in. This means these actions have to be set on event UC Froala Before Initialization. The plug-in doesn’t restrict the number of true (or false) actions - multiple true (or false) actions can be used in one dynamic action.

Image Browser Parameters

This action allows a developer to define an anonymous JavaScript function returning Froala imageManagerLoadParams option used to load images in Froala images browser. The function is executed just before opening Froala image browser. Defined parameters are used by the plug-in RESTful service to filter images to be shown to the end-user. A developer has to specify attribute Settings \ Function Returning JSON and the dynamic action affected elements indicating what plug-in instances are affected.

This action has to be executed on Froala Before Initialization event and can be implemented on global APEX page.

Attribute Settings\ Function Returning JSON

The attribute value has to be an anonymous function accepting only one parameter which is JSON describing the image browse parameters.

function( pBrowseImagesParams ) {
pBrowseImagesParams.folder = apex.item('P4_UPLOAD_FOLDER').getValue();
return pBrowseImagesParams;
}

Reset Value

The action retrieves the initial (ONLOAD) CLOB value for the plug-in instance via an AJAX call.

Update CLOB

This action updates the DRAFT CLOB value in the plug-in collection.

Upload Parameters

This action allows a developer to define an anonymous function returning upload parameters used by the plug-in RESTful service to upload images. Dynamic actions which implement the upload parameters have to be executed before the plug-in is initialized - the dynamic action has to be listening to the plug-in event UC Froala Before Initialization.

A developer has to specify Settings \ Function Returning JSON and dynamic action affected elements. The anonymous function is executed each time the image upload process is triggered.

Settings\ Function Returning JSON Attribute

The attribute value has to be an anonymous function accepting only one parameter which is JSON describing the image upload parameters.

function( pParams ) {
var 
uploadFlow = apex.item('P4_UPLOAD_IMAGE').getValue(),
folder     = apex.item('P4_UPLOAD_FOLDER').getValue()
;

pParams.customParam = uploadFlow;
pParams.folder      = folder;

return pParams;  
}

RESTful Image Handling

The plug-in integrates the Froala editor with Oracle APEX RESTful services in order to handle image upload. The plug-in requires four RESTful templates to be defined in an application:

Templates

All template handlers use IN and OUT parameters to handle RESTful image requests. IN parameters do not have to be registered with the RESTful template handler, but OUT parameters have to be defined as template handler parameters. This section describes all mandatory templates that are delivered with the plug-in sample application.

browse (GET)

The browse handler is used by the plug-in to implement the Froala uploaded image browser. The image browser is available after clicking a specific icon in the toolbar.

Handler Default Parameters

The plug-in uses four default parameters to handle RESTful requests to display uploaded images. The table below describes all parameters used by the plug-in which can be reference in the template handler PL/SQL, These parameters don’t have to be registered with the template handler.

Changing Parameters

In order to change the parameters, a developer has to override the Froala imageManagerLoadParams. Changing parameters can be done using an APEX item attribute Advanced \ JavaScript Initialization Code and the United Codes Rich Text Editor Pro (Extend) supporting plug-in.

function( pOptions ) {
//pOptions.imageManagerLoadParams is JSON object describing browse parameters
return pOptions;
}

function( pBrowseImagesParams ) {
pBrowseImagesParams.folder = apex.item('P4_UPLOAD_FOLDER').getValue();
return pBrowseImagesParams;
}

Handler Output

In order to make the image browser work with the Froala API, the browse template handler has to output an array of images in JSON format. Each array entry must be a JSON object describing an image stored in the database. The url, thumb, and tag properties are described by the Froala API imageManagerLoadURL option.

Example JSON output for browse handler is presented below:

[
{
"url":"pluginsplus\/ucfroalaapi\/get\/614"
},

...
]

Sample Application Definition

The sample application is delivered with an example package implementing PL/SQL used to browse uploaded images.

create or replace package body UC_FROALA_SAMPLE_REST as
...
procedure imageBrowse( 
p_session_id                    in number,  
p_access_token                  in varchar2,
p_app_user                      in varchar2,
p_application_id                in varchar2,
p_page_id                       in varchar2,
p_status                        out integer
)  
is  
v_sys_refcursor                 sys_refcursor;    
v_url                           varchar2(4000);    
v_access_token_valid            boolean;  
v_access_token                  uc_rte_access_token;
v_image_link                    varchar2(32767);  
begin  

v_access_token_valid := UC_FROALA_RTE.access_token_validate( p_access_token );  

if not v_access_token_valid then  
  raise_application_error(-20001, 'Invalid access token'); 
end if;  

v_access_token := uc_froala_rte.access_token_get_from_string( p_access_token );

v_url := v_access_token.url_get_image;

open v_sys_refcursor for  
  select     
    v_url||id       as "url"  
  from     
    UC_FROALA_SAMPLE_BLOBS    
  where
    session_id = p_session_id
;    
    
apex_json.write( v_sys_refcursor );

exception
when e_access_token_invalid then  
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_access_token', p_access_token);    
  apex_json.close_object;

when others then
  p_status := 500;
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_session_id'      , p_session_id);
  apex_json.write('p_access_token'    , p_access_token);
  apex_json.write('p_app_user'        , p_app_user);
  apex_json.write('p_application_id'  , p_application_id);
  apex_json.write('p_page_id'         , p_page_id);
  apex_json.close_object;  
end imageBrowse;  
...
end UC_FROALA_SAMPLE_REST;

delete (POST)

The delete template handler is used by the plug-in to delete uploaded images using the Froala image browser. In order to delete an image, the end-user has to open the image browser and hover over the image they wish to delete.

Handler Default Parameters

The plug-in uses 9 default parameters to handle RESTful requests to delete an image. The table below describes all parameters used by the plug-in which can be used within the template handler PL/SQL. All parameters except status don’t have to be registered as the handler parameters.

Changing Parameters

In order to change the parameters, a developer has to override the Froala imageManagerDeleteParams. Changing parameters can be done using an APEX item attribute Advanced \ JavaScript Initialization Code which is executed only once when the plug-in is initialized (page load).

function( pOptions ) {
//pOptions.imageManagerDeleteParams is JSON object describing browse parameters
return pOptions;
}

Handler Output

The delete handler outcome is not interpreted by the plug-in. The delete request can be only successful (HTTP status 200) or unsuccessful (HTTP status 4xx or 5xx).

Sample Application Definition

create or replace package body UC_FROALA_SAMPLE_REST as   
...  
procedure imageDelete(  
p_access_token                  in varchar2,  
p_session_id                    in varchar2,  
p_application_id                in varchar2,  
p_page_id                       in varchar2,  
p_app_user                      in varchar2,  
p_image_id                      in varchar2,  
p_status                        out integer  
)   
is   
v_access_token_valid            boolean;  
begin   

v_access_token_valid := UC_FROALA_RTE.access_token_validate( p_access_token );  

if not v_access_token_valid then  
  raise_application_error(-20001, 'Invalid access token');  
end if;  

delete from UC_FROALA_SAMPLE_BLOBS where id = p_image_id;    

if SQL%ROWCOUNT = 0 then    
  raise no_data_found;
end if;    

apex_json.open_object;    
  
apex_json.write( 'access_token'   , p_access_token   , true );  
apex_json.write( 'session_id'     , p_session_id     , true );  
apex_json.write( 'application_id' , p_application_id , true );  
apex_json.write( 'page_id'        , p_page_id        , true );  
apex_json.write( 'app_user'       , p_app_user       , true );  
apex_json.write( 'image_id'       , p_image_id       , true );  
apex_json.write( 'status'         , p_status         , true );      

apex_json.close_object;    

exception  
when no_data_found then
  p_status := 404;  
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_access_token', p_access_token);    
  apex_json.close_object;  

when e_access_token_invalid then  
  p_status := 403;
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_access_token', p_access_token);    
  apex_json.close_object;

when others then
  p_status := 500;
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_access_token'  , p_access_token);
  apex_json.write('p_session_id'    , p_session_id);
  apex_json.write('p_application_id', p_application_id);
  apex_json.write('p_page_id'       , p_page_id);
  apex_json.write('p_app_user'      , p_app_user);
  apex_json.write('p_image_id'      , p_image_id);      
  apex_json.close_object;
end imageDelete;  
...

end UC_FROALA_SAMPLE_REST;  

get/:fileid

The get template is used to display uploaded images embedded in CLOB content via an image src attribute. A link to the uploaded image is returned by the upload template handler and also for images displayed in the Froala image browser (browse template handler).

Handler Default Parameters

The template handler uses the URL parameter field and two OUT parameters that have to be registered as template handler parameters,

Changing Parameters

You can add new parameters following the Route Patterns syntax. If the get handler is defined as follows:

http://www.apexrnd.be/ords192/pluginsplus/ucfroalaapi/get/:fileid

it can be extended with new parameters added in the get handler URL

http://www.apexrnd.be/ords192/pluginsplus/ucfroalaapi/get/:fileid?a=1&b=2

Within the handler PL/SQL, values 1 and 2 can be referenced using bind variable syntax

declare
v_param_a varchar2(32767);
v_param_b varchar2(32767);
begin
v_param_a := :a;
v_param_b := :b;
end;

Handler Output

The output must be the content of the request image.

Sample Application Definition

create or replace package body UC_FROALA_SAMPLE_REST as   
...
procedure imageGet(  
p_file_id                       in number,  
p_status                        out integer,  
p_location                      out varchar2
)  
is  
v_file_content                  blob;  
v_file_mimetype                 varchar2(32767);  
v_image_link                    varchar2(32767);  
v_ords_alias                    varchar2(32767); 

begin  
select   
  FILE_MIMETYPE,   
  FILE_CONTENT   
into  
  v_file_mimetype,  
  v_file_content      
from   
  UC_FROALA_SAMPLE_BLOBS   
where   
  id = p_file_id  
;

v_ords_alias := getORDSAlias; 

v_image_link := v_ords_alias||'/'||c_rest_module_name||'/get/'||p_file_id;  

p_status := 200;  
p_location := v_image_link;  

sys.HTP.init;  
sys.OWA_UTIL.mime_header(v_file_mimetype, FALSE);  
sys.HTP.p('Content-Length: ' || DBMS_LOB.getlength(v_file_content));  
sys.HTP.p('Access-Control-Allow-Origin: *');  
sys.OWA_UTIL.http_header_close;  

sys.WPG_DOCLOAD.download_file(v_file_content);    
exception  
when no_data_found then  
  p_status := 404;

when others then
  p_status := 500;  
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_file_id'   , p_file_id);
  apex_json.close_object;  

end imageGet;  
...
end UC_FROALA_SAMPLE_REST;  

upload

The upload template handler is used by the plug-in to upload images on page submission when specific submit request is used.

Handler Default Parameters

The plug-in exposes 10 default parameters that can be used while uploading an image. The location and status parameters are required OUT parameters and have to be registered as handler parameters.

Changing Parameters

In order to change the parameters, a developer has to override the Froala imageUploadParams. Changing parameters can be done using an APEX item attribute Advanced \ JavaScript Initialization Code and the supporting plug-in United Codes Rich Text Editor Pro (Extend). The difference is that using an item attribute is a one-time action on the plug-in initialization while using the supporting plug-in allows developers to change the parameters dynamically using an anonymous JavaScript function.

function( pOptions ) {
//pOptions.imageUploadParams is JSON object describing browse parameters
return pOptions;
}

function( pBrowseImagesParams ) {
pBrowseImagesParams.folder = apex.item('P4_UPLOAD_FOLDER').getValue();
return pBrowseImagesParams;
}

Handler Output

In order to make the upload of images work properly, the upload template handler has to output a JSON describing the uploaded image.

Example JSON returned looks like this:

{
"link":"pluginsplus\/ucfroalaapi\/get\/984",
"data-image-id":984,
"data-image-temp-id": "ui-id-1"
}

Sample Application Definition

create or replace package body UC_FROALA_REST_API as   
...  
procedure imageUpload(  
p_access_token                  in varchar2,  
p_session_id                    in varchar2,  
p_application_id                in varchar2,  
p_page_id                       in varchar2,  
p_app_user                      in varchar2,      
p_image_name                    in varchar2,  
p_image_content                 in blob,  
p_image_mimetype                in varchar2,  
p_image_temp_id                 in varchar2,
p_status                        out integer,  
p_location                      out varchar2  
) is  
v_file_id                       number;  
v_image_link                    varchar2(32767);  
v_access_token                  uc_rte_access_token;
v_access_token_valid            boolean;  
v_ords_alias                    varchar2(32767); 
begin  
v_access_token_valid := UC_FROALA_RTE.access_token_validate( p_access_token );  

if not v_access_token_valid then  
  raise_application_error(-20001, 'Invalid access token');  
end if;  

v_access_token := uc_froala_rte.access_token_get_from_string( p_access_token );

insert into UC_FROALA_SAMPLE_BLOBS(    
  FILE_NAME,    
  FILE_MIMETYPE,    
  FILE_CONTENT,
  SESSION_ID
) values(    
  p_image_name,    
  p_image_mimetype,    
  p_image_content,
  p_session_id
) returning ID into v_file_id;    

v_image_link := v_access_token.url_get_image||v_file_id;

apex_json.open_object;
apex_json.write('link'                , v_image_link     , true);
apex_json.write('data-image-temp-id'  , p_image_temp_id  , true); 
apex_json.write('data-image-id'       , v_file_id        , true);  
apex_json.close_object;    

p_location  := v_image_link;  
p_status    := 200;

exception  
when e_access_token_invalid then  
  p_status := 500;  
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_access_token', p_access_token);    
  apex_json.close_object;  

when others then
  p_status := 500;  
  apex_json.open_object;    
  apex_json.write('error', SQLERRM);  
  apex_json.write('p_access_token'    , p_access_token);
  apex_json.write('p_session_id'      , p_session_id);
  apex_json.write('p_application_id'  , p_application_id);
  apex_json.write('p_page_id'         , p_page_id);
  apex_json.write('p_app_user'        , p_app_user);
  apex_json.write('p_image_name'      , p_image_name);
  apex_json.write('p_image_mimetype'  , p_image_mimetype);
  apex_json.write('p_image_temp_id'   , p_image_temp_id);
  apex_json.close_object;  
end imageUpload;   
...
end UC_FROALA_REST_API;  

Error Handling

The plug-in interprets the RESTful template handler output which must be a valid JSON object - based on the output the plug-in displays errors to the end-user.

The most commonly raised errors are described below. Additionally, the plug-in allows creating custom RESTful service logic for uploaded images that require raising a custom error displayed to end-users. By default, the Froala editor interprets RESTful requests as failures only when the HTTP status of the AJAX call is different than 200 (Client Error 4xx and Server Error 5xx).

Custom Error Message for Custom RESTful Logic

The RESTful request can be terminated by assigning HTTP status 4xx or 5xx to the status RESTful template handler parameter. Additionally, the template handler has to output JSON with the error property. For example, to terminate the image upload, the status parameter can be set to HTTP Server Error 500 along with JSON output containing the error property with the value set to Upload terminated with custom error message. See example code below:

create or replace package body UC_FROALA_SAMPLE_REST as   

...

procedure imageUpload(  
p_access_token    in varchar2,  
p_session_id      in varchar2,  
p_application_id  in varchar2,  
p_page_id         in varchar2,  
p_app_user        in varchar2,      
p_image_name      in varchar2,  
p_image_content   in blob,  
p_image_mimetype  in varchar2,  
p_status          in out number,  
p_location        in out varchar2  
) is  
...
begin  
...

p_status := 500; 

apex_json.open_object;    
apex_json.write('error', 'Upload terminated with custom error message.');  
apex_json.close_object;  

end imageUpload; 

...

end UC_FROALA_SAMPLE_REST;  

After uploading the image the plug-in displays the given error message to the end-user using the APEX JavaScript API apex.message.

RESTful Handler Output JSON Without Error Property Defined

When a RESTful request is terminated with HTTP status but the RESTful handler JSON output doesn’t include the error property, the plug-in raises a general error message Uploading image failed without error message defined.

RESTful Service PL/SQL Error

When a RESTful template handler raises a PL/SQL error, the RESTful request output is ORDS Internal Server Error. Because the plug-in expects valid JSON output, it displays the Upload image failed: JSON can’t be parsed message and the details of the error have to be checked using browser developer tools.

Invalid Access Token

When validating the plug-in access token fails, the plug-in displays an error Upload image failed: Invalid access token.

The Access Token

The access token is a secured string encoded by the plug-in PL/SQL using the DBMS_CRYPTO package. The UC_FROALA_RTE package includes a public function access_token_validate used by the example RESTful service UC_FROALA_REST_API package to validate RESTful image requests.

create or replace package UC_FROALA_RTE as

...

function access_token_validate (   
p_access_token in varchar2   
) return boolean;

...

end UC_FROALA_RTE;

The validation function accepts only one argument which is the RESTful template handler parameter accessToken. The example procedure handling an image upload looks like this (lines 11-15):

  procedure imageUpload(  
p_access_token in varchar2,  
...
p_status       in out number,  
p_location     in out varchar2  
) is  
...
v_access_token_valid boolean;  
...
begin  
v_access_token_valid := UC_FROALA_RTE.access_token_validate( p_access_token );  

if not v_access_token_valid then  
  raise e_access_token_invalid;  
end if;  

...
exception  
...
when e_access_token_invalid then  
  p_status := 500;  
  apex_json.open_object;    
  apex_json.write('error', g_error_invalid_access_token);  
  apex_json.write('accessToken', p_access_token);    
  apex_json.close_object;  
...
end imageUpload;  

This procedure is implemented in the Sample Application RESTful handler for the upload template handler (accessToken is passed to the procedure as p_access_token argument).

  
begin  
UC_FROALA_REST_API.imageUpload(  
p_access_token   => :accessToken,  
...
p_status         => :status,  
p_location       => :location  
);    
end;  

The Salt String

The default salt string used to generate an access token is defined in the UC_FROALA_SETTINGS package and should be changed after installing the plug-in.

create or replace package UC_FROALA_SETTINGS as   

g_froala_access_token varchar2(64) := '17273F940549E5B88416BEFDBF9C4BD4CC0E1F98283BA89B4907F6777B853F56';

end UC_FROALA_SETTINGS;

Using the plug-in access token to secure RESTful image requests is not mandatory but it is recommended as an additional security check.