Project: Plug-ins-Plus : Rich Text Editor Pro

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.

Requirements

Native APEX Rich Text Editor

United Codes Rich Text Editor Pro

1

CLOB support

(error)

(tick)

2

CLOB checksum validation

(error)

(tick)

3

Image handling

(question)

(tick)

4

RTL support

(tick)

(tick)

5

Translatable

(question)

(tick)

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

Toolbar customization

Use the supporting plug-in to define toolbar customizations on the APEX global page. Learn more in The Plug-in \ Supporting Plug-ins \ United Codes Rich Text Editor Pro (Extend)

The plug-in by default implements the following buttons

Paragraph

Button

Basic

Intermediate

Full

paragraphFormat

(error)

(tick)

(tick)

fontFamily

(error)

(tick)

(tick)

fontSize

(error)

(tick)

(tick)

bold

(tick)

(tick)

(tick)

italic

(tick)

(tick)

(tick)

underline

(error)

(tick)

(tick)

strikeThrough

(error)

(error)

(tick)

clearFormatting

(tick)

(tick)

(tick)

insertLink

(tick)

(tick)

(tick)

Rich

Button

Basic

Intermediate

Full

insertImage

(tick)

(tick)

(tick)

insertTable

(error)

(tick)

(tick)

specialCharacters

(error)

(error)

(tick)

insertHR

(error)

(tick)

(tick)

insertFile

(error)

(tick)

(tick)

insertVideo

(error)

(tick)

(tick)

emoticons

(error)

(error)

(tick)

Text

Button

Basic

Intermediate

Full

formatOL

(tick)

(tick)

(tick)

formatUL

(tick)

(tick)

(tick)

alignLeft

(error)

(tick)

(tick)

alignCenter

(error)

(tick)

(tick)

alignRight

(error)

(tick)

(tick)

alignJustify

(error)

(tick)

(tick)

outdent

(error)

(tick)

(tick)

indent

(error)

(tick)

(tick)

textColor

(error)

(tick)

(tick)

backgroundColor

(error)

(tick)

(tick)

lineHeight

(error)

(tick)

(tick)

quote

(error)

(error)

(tick)

inlineClass

(error)

(error)

(tick)

inlineStyle

(error)

(error)

(tick)

superscript

(error)

(error)

(tick)

subscript

(error)

(error)

(tick)

fontAwesome

(error)

(error)

(tick)

Misc

Button

Basic

Intermediate

Full

undo

(tick)

(tick)

(tick)

fullscreen

(tick)

(tick)

(tick)

print

(tick)

(tick)

(tick)

redo

(tick)

(tick)

(tick)

getPDF

(error)

(error)

(tick)

selectAll

(error)

(tick)

(tick)

html

(tick)

(tick)

(tick)

help

(tick)

(tick)

(tick)

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).

Attribute

Type

Description

1

Image Upload URL

Text

URL to RESTful template handling image uploads using the Froala editor

2

Image Browse URL

Text

URL to RESTful template which loads images into the Froala image browser

3

Image Delete URL

Text

URL to RESTful template handling the deletion of uploaded images from the database.

Application attributes can be overridden at the item level. See component attribute Settings \ Override Application Attributes

Component

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

Attribute

Type

Dependent on

Description

1

Settings

Checkbox

  • Embed Images as Inline Base64

  • Enable Browser Built-in Spell Check

  • Enable Sticky Toolbar

  • Enable TUI Image Editor

  • Override Application Attributes

  • Validate CLOB Checksum on Page Submit

-

Embed Images as Inline Base64

  • when checked - all images dropped into the Froala editor are added as inline base64 images. Inline base64 images increase a CLOB length. Images added from the Froala image browser can’t be added as inline base64 images.

  • when not checked - all images are uploaded and saved to the database using the plug-in RESTful service

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

-

The given value (“X”) is used to calculate the Froala heightMin and maxHeight properties.

{
  ...
  heightMin: (X-1)+'px';
  heightMax: X+'px';
  ...
}

The Froala editor height attribute is applied to the editor working area - it doesn’t include toolbar and footer.

6

Image Upload URL

Text

Settings

  • Override Application Attributes is checked

URL to RESTful template handling image upload using the Froala editor.

Attribute value overrides the application scope of the plug-in settings for the selected item.

7

Image Browse URL

Text

Settings

  • Override Application Attributes is checked

URL to RESTful template which loads images for the Froala image browser.

Attribute value overrides the application scope of the plug-in settings for the selected item.

8

Image Delete URL

Text

Settings

  • Override Application Attributes is checked

URL to RESTful template handling the deletion of uploaded images from the database.

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.

Property

Type

Description

1

this.data.reason

Text

The reason property indicates whether the event was triggered by dynamic action Refresh or by the supporting plug-in.

Possible values are the following:

  • froalaresetclob

  • apexdarefresh

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.

Property

Type

Description

1

this.data.reason

Text

The reason property indicates whether the event was triggered by dynamic action Refresh or by the supporting plug-in.

Possible values are the following:

  • froalaresetclob

  • apexdarefresh

UC Froala CLOB updated

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

Property

Type

Description

1

this.data.checksum

Number

The current checksum of DRAFT CLOB

UC Froala CLOB reset

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

Property

Type

Description

1

this.data.checksum

Number

The ONLOAD CLOB checksum

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

Property

Type

Description

1

this.data.option

Text

The Froala editor or the plug-in option name that has been changed. Possible values are:

  • base64images

  • imageUploadParams

  • imageManagerLoadParams

2

this.data.before

Text / JSON / Boolean

The option value before a change

3

this.data.after

Text / JSON / Boolean

The option value after a change

4

this.data.triggeringElement

DOM object

The triggering element that executed the action

this.data.triggeringElement is available only for Disable Base64 Images and Enable Base64 Images

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

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

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

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

UC Froala Content Changed

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

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

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

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

Learn more about codes and messages in the Froala documentation for the Froala event imageManager.error

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

2

this.data.errorCode

Number

The Froala error code

3

this.data.errorMessage

Text

The Froala error message

4

this.data.response

Text

The RESTful delete service output

UC Froala Image Upload Error

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

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

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

2

this.data.errorCode

Number

The Froala error code

3

this.data.errorMessage

Text

The Froala error message

4

this.data.response

Text

The RESTful delete service output

UC Froala Image Inserted

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

  • an image is added to the Froala editor

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

2

this.data.inline

Boolean

When

  • true then an image is inline base64

  • false then an image was uploaded

3

this.data.imageId

Text

An id of an image within CLOB content. When the image is inline base64 then the id is set as data-temp-id attribute. Otherwise the id is set as data-image-id.

4

this.data.imageName

Text

Image file name

Applicable only for uploaded images

5

this.data.imageMimeType

Text

Image MIME type

Applicable only for uploaded images

6

this.data.imageUrl

Text

Image RESTful URL

Applicable only for uploaded images

UC Froala Image Removed

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

  • an image is added to the Froala editor

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

2

3

this.data.inline

Boolean

When

  • true then an image is inline base64

  • false then an image was uploaded

4

this.data.imageId

Text

An id of an image within CLOB content. When the image is inline base64 then the id is set as data-temp-id attribute. Otherwise the id is set as data-image-id.

5

this.data.imageName

Text

Image file name

Applicable only for uploaded images

6

this.data.imageMimeType

Text

Image MIME type

Applicable only for uploaded images

7

this.data.imageUrl

Text

Image RESTful URL

Applicable only for uploaded images

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 the this.data JSON object described below

Property

Type

Description

1

this.data.options

JSON object

The Froala option currently used by the plug-in

2

this.data.action

Text

  • add - image is added to collection

  • remove - image is removed from collection

  • init- the plug-in initialization

The collection state is cleared when the plug-in is rendered.

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;

getChecksum

The function accepts only CLOB and returns a calculated checksum.

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.

Argument

Description

p_item_name

An APEX item name implementing the plug-in

p_type

Type of CLOB to be stored in the plug-in collection. The valid values are ONLOAD and DRAFT

p_value

The value of the CLOB to be stored in the collection

p_set_session_state

Determines whether APEX session state for the given APEX item will be updated.

If set to

  • TRUE then the session state of the given item is set to CLOB checksum specified as p_value,

  • FALSE then the session state is not changed

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

The plug-in embeds images in CLOB differently depending on the current plug-in settings and method of adding images. An image can be embedded in the CLOB content as a base64 inline image or as an image referencing the APEX RESTful service URL. Adding or removing images triggers the plug-in event UC Froala Images In Collection.

Learn more about the event in section The plug-in \ Events

Inlines base64 images

In order to enable inline base64 images, the following requirements must be met:

  1. the plug-in has to support inline base64 images

  2. an image is added by drag and drop or is copied and pasted (in the browser window)

The inline base64 image support can be enabled on-page load by selecting the plug-in setting via the Settings \ Embed Images as Inline Base64 item attribute or can be enabled on the fly using the supporting plug-in United Codes Rich Text Editor Pro (Extend) \ Enable Inline Base64 images. Images stored as inline base64 images have the image content embedded directly in the image src attribute thus they increase the length of the CLOB content.

Images already uploaded and previewed in the Froala image browser can be added as inline base64 images, but they have to be manually copied and pasted by the end-user ( right mouse click on an image \ Copy an image).

Uploaded images

If support for base64 images is disabled then all images added to the Froala editor will be uploaded using the RESTful service. Otherwise, images are uploaded only when the end-user selects the Froala upload from the editor toolbar. Uploaded images are embedded as images referencing the RESTful service URL.

Images in the plug-in collection

Information about images added to or removed from the Froala editor is stored in the plug-in collection. The information about images is only valid from page-load to the first submission of a page (excluding page submission terminated by validation errors without reloading a page). This behavior is implemented in order to allow developers to handle images added or removed from CLOB on-page submission. Information stored within the collection will vary depending on whether the end-user is editing an existing CLOB containing images or the end-user is about to save a new CLOB.

Reloading the page results in emptying the image's collection state.

The information stored about added or removed images varies depending on the image type (inline base64 image vs uploaded image). Learn more about images in the collection in the APEX integration \ Item session state \ Support for CLOB values section.

Creating a new CLOB

The end-user is working on an empty CLOB. Adding new images (inline or uploaded) adds a new row to the collection describing the added image - column c009 contains text ADDED. If the end-user removes the image before saving the CLOB content the image row with status ADDED is removed. If he does not remove the image and submits the page (to save the CLOB content) then the APEX page processes have access to information about the added image through the collection state.

Editing existing CLOB with images

The end-user is working on an existing CLOB saved in the database - the CLOB content contains inline and uploaded images. Removing the inline image from CLOB won’t store information in the collection while removing the uploaded image will add a new row to the collection with status REMOVED (column c009). Adding new images adds a new row to the collection describing an image.

This behavior is implemented in order to handle removed images from CLOB content that were previously uploaded using the RESTful service.

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 that is 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 state on page load

  2. CLOB state after page submission (or after updating the CLOB using the AJAX call)

  3. added or removed images using the Froala editor plug-in

  4. checking CLOB checksum on page submission

The collection columns are described as follows:

Column

Purpose

Description

c001

The name of APEX item implementing the plug-in

The item name is static for all information stored in the collection for a particular instance of the plug-in

c002

General information about the purpose of the row

Possible values are:

  • ONLOAD - row contains CLOB content used to render an item value

  • DRAFT - row contains CLOB content updated on-page submission or by using the supporting dynamic action plug-in

  • PROCESS_LOAD - row contains the native process id that was used to load CLOB content into the collection

  • IMAGE - row contains information about an image added into or removed from the Froala editor

  • CLASS - row contains the class name added in Item \ Advanced \ CSS Classes. If multiple classes were used you can expect multiple rows in the collection

c003

Currently not used

Currently not used

c004

Image type

Possible values:

  • INLINE - row contains information about inline-image added/removed from the Froala editor

  • UPLOAD - row contains information about uploaded imaged added/removed from the Froala editor

c005

Image id

When column c004 equals

  • INLINE then this column contains JavaScript generated ID (temporary)

  • UPLOAD then this column contains the file ID used by RESTful service

c006

Image filename

When column c004 equals

  • INLINE then this column is always null

  • UPLOAD then this column contains the file MIME type returned by RESTful service.

c007

Image MIME type

When column c004 equals

  • INLINE then this column is always null

  • UPLOAD then this column contains the file MIME type returned by RESTful service.

c008

Image URL

When column c004 equals

  • INLINE then this column is always null

  • UPLOAD then this column contains image URL (RESTful get handler)

c009

Image Froala status

Possible values:

  • ADDED - the image has been added after the plug-in was initialized.

  • REMOVED - the image has been removed after the plug-in was initialized.

c010

Item class

An item class defined via item attribute Item\Advanced\CSS Classes. If multiple classes are set then multiple rows are created.

n001

CLOB checksum

The current checksum calculated for CLOB stored in column clob001.

n002

CLOB length

The current length of CLOB stored in column clob001

n003

APEX process Id

When the United Codes Rich Text Editor Pro (Process) supporting plug-in is used to load the CLOB value then this column contains the native APEX process ID which implements the supporting plug-in.

clob001

CLOB content

The CLOB content is dependent on c002 column value. When

  • c002 = ONLOAD then ONLOAD CLOB content

  • c002 = DRAFT then DRAFT CLOB content

  • c002 = IMAGE and c004 = INLINE then value of image src attribute

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 was 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 submit requests should be used to perform the plug-in built-in CLOB checksum validation.

Item Attribute Integration

Appearance

Attribute

Supported

Description

Template

(warning)

All native templates besides Floating are supported

Template Options

(warning)

Template options not supported:

  • Common \ Stretch Form Item

  • Common \ Size

CSS Classes

(tick)

Natively supported, doesn’t apply to the plug-in itself.

Format Mask

(error)

Doesn’t apply to the plug-in

Value Placeholder

(tick)

Given value is used as the Froala placeholder

Validation

Attribute

Supported

Description

Value Required

(tick)

The plug-in supports HTML5 validation check on page submission.

Advanced

Attribute

Supported

Description

CSS Classes

(tick)

Given classes are added to the textarea on which the plug-in is initialized.

Custom Attributes

(tick)

Given attributes are added to the textarea on which the plug-in is initialized.

Pre Text

(tick)

-

Post Text

(tick)

-

Warn on Unsaved Changes

(tick)

-

JavaScript Initialization Code

(tick)

Use this attribute to override Froala options using an anonymous JavaScript function returning options at the item level.

function( pOptions ) {
  return pOptions;
}

This attribute is evaluated before the United Codes Rich Text Editor Pro (extend) supporting plug-in .

Source

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

Attribute

Supported

Description

Form Region

(error)

-

Type

(warning)

Only NULL and SQL Query (return single value) are supported. Other types are limited to the 32 767 limitation, thus they are not supported.

Used

(tick)

When

  • Always, replacing any existing value in session state is selected, then the item source attribute is used.

  • Only when current value in session state is null is selected, then the plug-in DRAFT CLOB is used.

Maintain Session State

(tick)

-

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

Dynamic Action

Supported

Description

Set value

(tick)

Sets a new value in the Froala editor. The plug-in respects the Suppress Change Event flag.

Clear

(tick)

Clears the Froala editor’s value. Triggers change event.

Disable

(tick)

Disables the Froala editor and toolbar.

Enable

(tick)

Enables the Froala editor and toolbar.

Hide

(tick)

Hides the Froala editor.

Show

(tick)

Shows the Froala editor

Refresh

(tick)

Fetches the DRAFT CLOB value from the collection and sets the value of the Froala editor

Set Focus

(tick)

Sets focus on the Froala editor.

APEX Item JavaScript Integration

API

Description

apex.item.getValue

Returns the current value (HTML) of the Froala editor

apex.item.addValue

Adds the value to the Froala editor

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 3 actions:

  • Clear CLOB

  • Load CLOB

  • Update CLOB

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:

Attribute

Type

Required

Description

Item

Page item

Yes

Item implementing the plug-in

Other Page Item(s)

Page item(s)

No

Page items to be cleared using APEX API APEX_UTIL.SET_SESSION_STATE

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:

Attribute

Type

Required

Description

Item

Page item

Yes

Item implementing the plug-in

SQL Query

SQL Query

Yes

Valid SQL Query returning CLOB content. For example:

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:

Attribute

Type

Required

Description

Item

Page item

Yes

Item implementing the plug-in

Function Body returning CLOB

PL/SQL Code

Yes

Valid anonymous PL/SQL code with return statement. For example:

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:

Attribute

Type

Required

Description

Item

Page item

Yes

Item name implementing the plug-in

Schema

Text

Yes

Schema that owns the table

Table Name

Text

Yes

The case-sensitive table or view name.

CLOB Column Name

Text

Yes

The column name which stores the CLOB content

PK(s) Column(s) Name(s)

Text

Yes

Comma separated list of primary key columns needed to fetch the CLOB

Item(s) Containing PK(s) Value(s)

Page Item(s)

Yes

Comma separated list of APEX page items containing primary keys values

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.

Attribute

Type

Required

Description

Item

Page item

Yes

Item implementing the plug-in

PL/SQL Code

PL/SQL Code

Yes

Valid anonymous PL/SQL code with return statement. For example:

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.

Attribute

Type

Required

Description

Item

Page item

Yes

Item name implementing the plug-in

Schema

Text

Yes

Schema that owns the table

Table Name

Text

Yes

The case-sensitive table or view name.

CLOB Column Name

Text

Yes

The column name which stores the CLOB content

PK(s) Column(s) Name(s)

Text

Yes

Comma separated list of primary key columns needed to fetch the CLOB

Item(s) Containing PK(s) Value(s)

Page Item(s)

Yes

Comma separated list of APEX page items containing primary keys values

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.

Action

Description

Uses DA Affected Elements

Change Toolbar

Allows changing the predefined toolbar preset. It can add or remove buttons from Froala toolbar, change the number of visible buttons in a group ,or remove an entire toolbar group.

(error)

Change Settings

Allows changing the Froala settings

(error)

Disable Base64 Images

When base64 images are disabled then images dripped into Froala editor are uploaded

(tick)

Enable Base64 Images

When base64 images are enabled then images dropped into Froala editor are embedded as inline base64 images

(tick)

Image Browser Parameters

Allows defining an anonymous JavaScript function to change the Froala image browse parameters that are available for RESTful browse service

(tick)

Reset value

Resets the content of Froala editor to the ONLOAD CLOB using an AJAX request

(tick)

Update CLOB

Updates the DRAFT CLOB in the plug-in collection with the current contents of Froala editor

(tick)

Upload Parameters

Allows defining an anonymous JavaScript function to change the Froala image upload parameters that are available for RESTful upload service

(tick)

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.

The dynamic action which implements Change Toolbar can be defined both on the page where the plug-in instance exists and on the APEX global page.

Toolbar Action

Description

Additional attribute(s) to set

Change Number of Visible Buttons

Changes the number of buttons visible in the given Froala toolbar group

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

  • Settings / Buttons Visible - new number of buttons visible in selected group

Add Button

Adds the selected Froala button to specified Froala toolbar group in the given position

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

  • Settings / Button - Froala button to be added to selected group

  • Settings / Button Position - position of the new button in the selected group

Add Buttons

Adds multiple buttons to the specified Froala toolbar group in the given position

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

  • Settings / Buttons - comma-separated list of Froala buttons to be added

  • Settings / Button Position - position of new button in the selected group

Remove Button From Group

Removes the selected Froala button from the specified Froala toolbar group

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

  • Settings / Button - Froala button to be removed from the selected group

Remove All Buttons From Group

Removes all the buttons from selected toolbar group

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

Remove All Buttons

Removes all buttons from all toolbar groups.

None

Remove Buttons From Group

Removes multiple buttons from the selected Froala toolbar group

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

  • Settings / Buttons - comma-separated list of Froala buttons to be removed

Remove Group

Removes a selected group from Froala Toolbar

A developer has to specify:

  • Settings / Group - Froala toolbar group to be updated

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.

The dynamic action which implements Change Settings can be defined both on the page where the plug-in instance is created and on APEX global page.

Setting

Description

Additional attribute(s) to set

Allow Image Pasting from Clipboard

When toggled

  • on - copy and pasting images from the browser window is enabled

  • off - copy and pasting images from the browser window is disabled

A developer has to toggle the switch using Settings / Value

Allow Resizing Image with Mouse

When toggled

  • on - resizing images with mouse is enabled

  • off - resizing images with mouse is disabled

A developer has to toggle the switch using Settings / Value

Browser Spell check

When toggled

  • on - browser spell check is enabled for Froala editor

  • off - browser spell check is disabled for Froala editor

A developer has to toggle the switch using Settings / Value

Direction Right To Left Enabled

When toggled

  • on - RTL is forced irrespective of APEX language

  • off - RTL is enabled only for APEX languages supporting RTL

A developer has to toggle the switch using Settings / Value

Maximum Height

Overrides the item attribute Settings \ Height

A developer has to define the new maximum height in pixels using Settings / Value

Minimum Height

Overrides the item attribute Settings \ Height

A developer has to define the new minimum height in pixels using Settings / Value

Placeholder Text

Overrides the item attribute Appearance \ Value Placeholder

A developer has to define the new placeholder text using Settings / Value

Show Current Font Family

When toggled

  • on - the currently applied font family name is shown in the Froala toolbar

  • off - simple dropdown is shown

A developer has to toggle the switch using Settings / Value

Show Current Font Size Selection

When toggled

  • on - the currently applied font font size is shown in the Froala toolbar

  • off - simple dropdown is shown

A developer has to toggle the switch using Settings / Value

Show Current Paragraph Selection

When toggled

  • on - the currently applied paragraph style is shown in the Froala toolbar

  • off - simple dropdown is shown

A developer has to toggle the switch using Settings / Value

Sticky Toolbar

When toggled

  • on - the Froala toolbar is sticky irrespective of the item attribute Settings \ Enable Sticky Toolbar

  • off - the Froala toolbar is not sticky irrespective of the item attribute Settings \ Enable Sticky Toolbar

A developer has to toggle the switch using Settings / Value

Sticky Toolbar Top Offset

Overrides the item attribute Settings \ Enable Sticky Toolbar

A developer has to define the new toolbar offset in pixels using Settings / Value

Width

Sets a fixed width for the Froala editor

A developer has to define the new width in pixels using Settings / Value

Disable Base64 Images

This action can be executed on the fly after the plug-in is initialized. When executed, all images dropped into the Froala editor will be uploaded using a defined RESTful upload service.

The dynamic action which implements this action uses affected elements to determine which the plug-in instances are not allowed to embed inline base64 images. When affected elements are not set, all the plug-in instances (on the page) are affected. Otherwise, only those specified in the affected elements attribute.

Enable Base64 Images

This action can be executed on the fly after the plug-in is initialized. When executed, all images dropped into the Froala editor will be embedded as inline base64 images. Base64 images increase CLOB length.

The dynamic action which implements this action uses affected elements to determine which the plug-in instances are allowed to embed inline base64 images. When affected elements are not set, all the plug-in instances (on the page) are affected. Otherwise, only those specified in the affected elements attribute.

Image Browser Parameters

This action allows a developer to define an anonymous function returning upload parameters used by the plug-in RESTful service to upload images. The anonymous function is executed each time the dynamic action event is triggered. This action can be executed on the fly after the plug-in is initialized.

A developer has to specify Settings \ Function Returning JSON and dynamic action affected elements.

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;
}

To learn more about image browse parameters see the RESTful image upload section.

The action uses dynamic action affected elements to determine which the plug-in instances can use the defined image browser parameters. When affected elements are not set, all the plug-in instances (on the page) are affected. Otherwise, only those specified in the affected elements attribute.

Reset Value

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

Learn more about ONLOAD CLOB in the APEX integration \ Item session state \ Support for CLOB values section.

The action uses dynamic action affected elements to determine which instances will be reset to the ONLOAD CLOB. When affected elements are not set, all the plug-in instances (on the page) are reset. Otherwise, only those specified in the affected elements attribute.

Update CLOB

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

Learn more about the DRAFT CLOB in the APEX integration \ Item session state \ Support for CLOB values section.

The action uses dynamic action affected elements to determine which instances will be updated. When affected elements are not set, all the plug-in instances (on the page) are updated. Otherwise, only those specified in the affected elements attribute.

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 that implement the upload parameters have to be executed before the plug-in is initialized - on 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;  
}

To learn more about browse image parameters see the RESTful image upload section.

The action uses dynamic action affected elements to determine which instances of the plug-in will use the defined anonymous function. When affected elements are not set, all the plug-in instances (on the page) are updated. Otherwise, only those specified in the affected elements attribute.

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:

Template

HTTP Method

Description

browse

GET

Template is used to browse previously uploaded images stored in the database.

delete

POST

Template is used to delete images displayed in the Froala image browser.

get/:fileid

GET

Template is used to display uploaded images that are embedded in CLOB content.

upload

POST

Template is used to handle image upload using the plug-in.

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.

The example implementation of all templates is delivered with the plug-in sample application. See the plug-in Sample Application to learn about example RESTful service definition.

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.

The RESTful template handler logic can be changed and adjusted by extending the parameters used by the request. Extra parameters can be used directly in the handler PL/SQL to display different images depending on a parameter value.

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.

Parameter

Bind variable

Description

1

sessionId

:sessionId

Current session id

2

accessToken

:accessToken

The plug-in Access Token generated from the plug-in PL/SQL

3

appUser

:appUser

Current end-user name

4

applicationId

:applicationId

Current application id

5

pageId

:pageId

Current page id

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.

Description

Example

JavaScript Initialization Code

One-time action executed when the plug-in is initialized (Item Attributes \ Advanced \ JavaScript Initialization Code).

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

United Codes Rich Text Editor Pro (Extend) \ Image Browser Parameters

Using the supporting plug-in allows overriding the browse parameters on the fly - for example when an APEX item is changed.

Learn more in Supporting plug-ins \ United Codes Rich Text Editor Pro (Extend) \ Image Browser Parameters

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.

JSON property

Required

Description

1

image-id

Yes

Used by the plug-in to identify the image id from the database

2

image-mimetype

Yes

Used by the plug-in to identify the image id from the database

3

image-name

Yes

Used by the plug-in to identify the image id from the database

4

image-url

Yes

Used by the plug-in to identify the image id from the database

5

url

Yes

Used by the Froala editor to set the src attribute of an image

6

thumb

No

The property is recommended to render thumbnails of images instead of full sized images in the Froala image browser.

7

tag

No

Froala docs do not describe how tag property is used by the editor.

Example JSON output for browse handler is presented below:

[
  {
    "image-id":614,
    "file-mimetype":"image\/jpeg",
    "file-name":"ball.jpg",
    "image-url":"pluginsplus\/ucfroalaapi\/get\/614",
    "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.

update the code at the very end

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
  )  
  is  
    c sys_refcursor;    
    v_url varchar2(4000);    
    v_ords_alias varchar2(32767); 
    v_access_token_valid boolean;  
    e_access_token_invalid exception;  
  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;  
  
    v_ords_alias := getORDSAlias; 
 
    v_url := v_ords_alias||'/'||g_rest_module_name||'/get/';  
 
    open c for  
      select     
        id              as "image-id", -- important, must be implemented  
        FILE_MIMETYPE   as "image-mimetype",  
        FILE_NAME       as "image-name",   
        v_url||id       as "image-url",  
        v_url||id       as "url"  
      from     
        UC_FROALA_SAMPLE_BLOBS    
      where
        session_id = p_session_id
    ;    
        
    apex_json.write(c);    
  
  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.

Bind Variable

Description

1

sessionId

Current session id

2

accessToken

The plug-in Access Token generated from the plug-in PL/SQL

3

appUser

Current end-user name

4

applicationId

Current application id

5

pageId

Current page id

6

imageUrl

An image URL

7

imageId

An image id

8

imageName

An image file name

9

status

The parameter must be registered as a RESTful template parameter with following attributes:

  • Name “X-APEX-STATUS-CODE”

  • Bind Variable “status“

  • Access Method “OUT“

  • Source Type “HTTP HEADER“

  • Data Type “STRING“

The status is used to terminate the delete request when custom logic is required.

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_url       in varchar2,  
    p_image_id        in varchar2,  
    p_image_name      in varchar2,  
    p_status          in out number  
  )   
  is   
    v_access_token_valid boolean;  
    e_access_token_invalid exception;  
  
  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;  
  
    delete from UC_FROALA_SAMPLE_BLOBS where id = p_image_id;    
      
    if SQL%ROWCOUNT = 0 then    
      p_status := 404;    
    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_url'      , p_image_url      , true );  
    apex_json.write( 'image_id'       , p_image_id       , true );  
    apex_json.write( 'image_name'     , p_image_name     , true );  
    apex_json.write( 'status'         , p_status         , true );      
  
    apex_json.close_object;    
  
  exception  
    when e_access_token_invalid then  
      p_status := 403;  
      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 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,

Parameter

Description

1

fileid

An ID of the image that has to be fetched and displayed using the RESTful URL

2

location

The parameter must be registered as a RESTful template parameter with the following attributes:

  • Name “location”

  • Bind Variable “location“

  • Access Method “OUT“

  • Source Type “HTTP HEADER“

  • Data Type “STRING“

3

status

The parameter must be registered as a RESTful template parameter with the following attributes:

  • Name “X-APEX-STATUS-CODE”

  • Bind Variable “status“

  • Access Method “OUT“

  • Source Type “HTTP HEADER“

  • Data Type “STRING“

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.

See Sample Application Definition.

Sample Application Definition

create or replace package body UC_FROALA_SAMPLE_REST as   
  ...
  procedure imageGet(  
    p_session_id  in number,  
    p_file_id     in number,  
    p_status      in out number,  
    p_location    in out varchar2  
  )  
  is  
    v_file_content blob;  
    v_file_mimetype varchar2(32767);  
    v_link varchar2(32767);  
 
    v_ords_alias varchar2(32767); 
 
    e_no_data_found exception;  
  begin  
    begin  
      select   
        FILE_MIMETYPE,   
        FILE_CONTENT   
      into  
        v_file_mimetype,  
        v_file_content      
      from   
        UC_FROALA_SAMPLE_BLOBS   
      where   
        id = p_file_id  
      ;  
  
    exception  
      when no_data_found then  
        raise e_no_data_found;  
    end;  
 
    v_ords_alias := getORDSAlias; 
 
    v_link := v_ords_alias||'/'||g_rest_module_name||'/get/'||p_file_id;  
  
    p_status := 200;  
    p_location := v_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.OWA_UTIL.http_header_close;  
  
    sys.WPG_DOCLOAD.download_file(v_file_content);    
  
  exception  
    when e_no_data_found then  
      p_status := 404;  
  
  end imageGet; 
  ...
end UC_FROALA_SAMPLE_REST;  

upload

The upload template handler is used by the plug-in to upload images. The end-user can upload images by dragging and dropping images from their system or by selecting an image to upload.

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.

Parameter

Type

Description

1

sessionId

IN

Current session id

2

accessToken

IN

The plug-in Access Token generated from the plug-in PL/SQL

3

applicationId

IN

Current application id

4

pageId

IN

Current page id

5

appUser

IN

Current end-user username

6

filename

IN

A filename of an image

7

body

IN

A contents of an image

8

content_type

IN

A MIME type of an image

9

location

OUT

The status parameter must be registered as a RESTful template parameter with the following attributes:

  • Name “location”

  • Bind Variable “location“

  • Access Method “OUT“

  • Source Type “HTTP HEADER“

  • Data Type “STRING“

10

status

OUT

The status parameter must be registered as a RESTful template parameter with the following attributes:

  • Name “X-APEX-STATUS-CODE”

  • Bind Variable “status“

  • Access Method “OUT“

  • Source Type “HTTP HEADER“

  • Data Type “STRING“

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.

Description

Example

JavaScript Initialization Code

One-time action executed when the plug-in is initialized (Item Attributes \ Advanced \ JavaScript Initialization Code).

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

United Codes Rich Text Editor Pro (Extend) \ Image Browser Parameters

Using the supporting plug-in allows overriding the browse parameters on the fly each time an image is uploaded.

Learn more in Supporting plug-ins \ United Codes Rich Text Editor Pro (Extend) \ Upload Parameters

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.

JSON property

Required

Description

image-id

Yes

Used by the plug-in to identify the image id from the database

image-mimetype

Yes

Used by the plug-in to identify the image id from the database

image-name

Yes

Used by the plug-in to identify the image id from the database

image-url

Yes

Used by the plug-in to identify the image id from the database

link

Yes

Used by the Froala editor to set the src attribute of an uploaded image

Example JSON returned looks like this:

{
  "link":"pluginsplus\/ucfroalaapi\/get\/984",
  "image-id":984,
  "image-mimetype":"image\/jpeg",
  "image-name":"sample.jpg",
  "image-url":"pluginsplus\/ucfroalaapi\/get\/984"
}

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_status          in out number,  
    p_location        in out varchar2  
  ) is  
    v_file_id number;  
    v_link varchar2(32767);  
  
    v_access_token_valid boolean;  
    v_ords_alias varchar2(32767); 
    e_access_token_invalid exception;  
    e_no_error_property exception; 
    e_custom_error exception; 
    v_test number; 
  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;  
 
    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_ords_alias := getORDSAlias; 
 
    v_link := v_ords_alias||'/'||g_rest_module_name||'/get/'||v_file_id;  
 
    apex_json.open_object;    
    apex_json.write('link'          , v_link           , true );
    apex_json.write('image-id'      , v_file_id        , true);  
    apex_json.write('image-mimetype', p_image_mimetype , true);  
    apex_json.write('image-name'    , p_image_name     , true);  
    apex_json.write('image-url'     , v_link           , true);  
    apex_json.close_object;    

    p_location  := v_link;  
    p_status    := 200;

  exception  
    when e_custom_error then 
      p_status := 500; 
      apex_json.open_object;    
      apex_json.write('error', 'Upload terminated with custom error message.');  
      apex_json.write('accessToken', p_access_token);    
      apex_json.close_object;  
 
    when e_no_error_property then 
      p_status := 500; 
      apex_json.open_object;    
      apex_json.write('accessToken', p_access_token);    
      apex_json.close_object;  
 
    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;  
  ...
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.