United Codes Rich Text Editor Pro (Extend)

Overview

The supporting dynamic action plug-in is an easy way to customize the Froala editor options using Oracle APEX dynamic actions. Additionally, the plug-in exposes two actions manipulating rich HTML text in the session state.

The plug-in exposes the following actions:

• Change Toolbar
• Change Settings
• Image Browser Parameters
• Reset value
• Update CLOB
• Upload Parameters

Initializing event

The plug-in actions (except for Reset Value and Update CLOB) require creating dynamic action on the item plug-in event named UC Froala Before Initialization.

The event is triggered right before the core plug-in is initialized. The item plug-in is aware of all dynamic actions listening to the plug-in event, and waits until all dynamic actions are successfully executed. Once all dynamic actions are processed, the item plug-in finishes initialization, including provided customizations.

Actions Reset Value, and Update CLOB can be bound with APEX buttons (or other DOM nodes) with any event, for example, click event (click).

Triggering element

A developer can decide whether the customization will be applied for specified plug-in instances or should be executed when a dynamic action is triggered but only for core plug-in instances narrowed by dynamic action affected elements.

The table below presents supported dynamic action triggering elements (selection type)

Triggering element	Supported
Item(s)
Button
Region
Column(s)
jQuery Selection
JavaScript Expression

Affected Elements

When a dynamic action triggering element includes multiple plug-in instances, a developer can use dynamic action affected elements to narrow plug-in instances to customize. If a dynamic action affected elements are not set, all plug-in instances triggering the event UC Froala Before Initialization are customized.

The plug-in supports the following affected element types:

• Item(s)
• jQuery Selector

Number of true actions

The plug-in doesn't limit the number of true (or false) actions - multiple actions can be used in one dynamic action.

Global page implementation

The plug-in supports the Oracle APEX global page to customize all core plug-in instances across an application. Using affected elements (for example, jQuery Selector), a developer can specify which core plug-in instances should be affected.

---

Change Toolbar

The action exposes an easy way to manipulate the editor's toolbar preset using a dynamic action interface in the page designer.

The action can be used to:

• change the number of visible buttons within the toolbar group
• add button(s) to toolbar group
• remove button(s) from toolbar group
• remove toolbar group

Change Number of Visible Buttons

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

A developer has to specify:

Attribute	Type
Group	Select list	The Froala toolbar group to be updated.
Buttons Visible	Number	a New number of buttons visible in the selected group.

Add Button

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

A developer has to specify the following:

Attribute	Type
Group	Select list	The Froala toolbar group to be updated
Button	Select list	The Froala button to be added to the selected group
Button Position	Number	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 the following:

Attribute	Type	Description
Group	Select list	Froala toolbar group to be updated
Buttons	Text	Comma-separated list of Froala buttons to be added
Button Position	Number	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 the following:

Attribute	Type	Description
Group	Select list	Froala toolbar group to be updated
Button	Select list	Froala button to be removed from the selected group

Remove All Buttons From Group

Removes all the buttons from the selected toolbar group.

A developer has to specify:

Attribute	Type	Description
Group	Select list	Froala toolbar group to be updated

Remove All Buttons

Removes all buttons from all toolbar groups.

Remove Buttons From Group

Removes multiple buttons from the selected Froala toolbar group.

A developer has to specify the following:

Attribute	Type	Description
Group	Select list	Froala toolbar group to be updated
Buttons	Text	Comma-separated list of Froala buttons to be removed

Remove Group

Removes a selected group from Froala Toolbar.

A developer has to specify:

Attribute	Type	Description
Group	Select list	Froala toolbar group to be removed

---

Change Settings

Allows changing twelve Froala options using a dynamic action interface in the page designer.

Allow Image Pasting From Clipboard

When enabled then, pasting images from clipboard is possible. Otherwise, pasting images has no effect in rich text document.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Enables or disabled image pasting from clipboard.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.imagePaste = false;
  return pOptions;
}

Allow Resizing Image with Mouse

When enabled then, resizing images with the mouse is possible. Otherwise, resizing images with the mouse is disabled.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Enables or disabled image resizing.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.imageResize = false;
  return pOptions;
}

Browser Spell check

When enabled, browser spell check is enabled for the Froala editor. Otherwise, a browser spell check is disabled.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Enables or disabled browser spell check.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.spellcheck = false;
  return pOptions;
}

Direction Right To Left Enabled

When enabled, then RTL is forced irrespective of APEX language. Otherwise, the RTL is enabled only for APEX languages supporting RTL.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Enables or disables RTL support

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.direction = 'auto'; // or: 'ltr', 'rtl'
  return pOptions;
}

Maximum Height

Overrides Froala option heightMax, calculated from an item attribute height. When set to 100% makes an editor height adapt to an editor's content.

A developer has to specify the following:

Attribute	Type	Description
Value	Text	A new maximum height of the editor working area.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.heightMax = 500;
  return pOptions;
}

Minimum Height

Overrides Froala option heightMin, calculated from an item attribute height.

A developer has to specify the following:

Attribute	Type	Description
Value	Text	A new minimum height of the editor working area.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.heightMin = 200;
  return pOptions;
}

Placeholder Text

Overrides a value of an item attribute Value Placeholder in the Appearance section.

A developer has to specify the following:

Attribute	Type	Description
Value	Text	A new placeholder text to be applied

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.placeholderText = 'Page item placeholder text';
  return pOptions;
}

Show Current Font Family

When enabled, the currently applied font size is shown in the editor toolbar. Otherwise, a simple select list is shown.

A developer has to specify:

Attribute	Type	Description
Value	Switch	Shows or hides the current font family.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.fontFamilySelection = false;
  return pOptions;
}

Show Current Font Size Selection

When enabled, the currently applied font size is shown in the editor toolbar. Otherwise, a simple select list is shown.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Shows or hides the current font size.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.fontSizeSelection = false;
  return pOptions;
}

Show Current Paragraph Selection

When enabled, the currently applied paragraph style is shown in the editor toolbar. Otherwise, a simple select list is shown.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Shows or hides the current font size.

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.paragraphFormatSelection = false;
  return pOptions;
}

Sticky Toolbar

Overrides a value of an item attribute Enable Sticky Toolbar in the plug-in Settings.

A developer has to specify the following:

Attribute	Type	Description
Value	Switch	Enable or disable toolbar stickiness

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.toolbarSticky = true;
  pOptions.toolbarStickyOffset = 48;
  return pOptions;
}

Sticky Toolbar Top Offset

Action overrides the item attribute Enable Sticky Toolbar in the plug-in Settings.

A developer has to specify the following:

Attribute	Type	Description
Value	Number	A new toolbar offset in pixels

This option can be defined using a page item attribute JavaScript Initialization Code. See an example below:

function (pOptions) {
  pOptions.toolbarSticky = true;
  pOptions.toolbarStickyOffset = 48;
  return pOptions;
}

---

Reset Value

The action restores the current editor's rich text HTML to the initial value (on-load CLOB) based on the current APEX session state over the AJAX call.

The action uses affected elements to determine which item plug-in is affected by the action. If affected elements are not set, all items available on a page are restored to on-load CLOB.

Learn more about the plug-in session state in the Integration with APEX \ About the APEX Session State.

---

Update CLOB

The action updates rich text document in Oracle APEX session state (as an item value) and in the plug-in session state (draft CLOB).

The action integrates the following APEX dynamic attributes:

• Execution Options \ Stop Execution On Error

• Execution Options \ Wait For Result

• Advanced \ JavaScript Initialization Code

• Affected Elements

Wait For Result

• Enabled - next true (or false) action(s) are executed only when the plug-in finishes updating rich text document in APEX and the plug-in session state.
• Disabled - next true (or false) action(s) are executed immiedietly without waiting for the action result.

Affected Elements

The action update CLOB uses affected elements to distinguish plug-in instances to be updated when the action is executed.

Selection Type	Example
Item(s)	P1_FROALA_1, P1_FROALA_2
jQuery Selector	.uc-froala--textarea

When dynamic action attribute affected elements is not set

When the attribute is not set, the plug-in updates all available instances based on dynamic action definition (dynamic action even an selection type). When dynamic action is bound with APEX button or JavaScript Expression document then the all instances on a page are updated.

Otherwise, the action attempts to update rich text document of dynamic action event target. For example when dynamic action listens to native Oracle APEX Change event on given page items, the action will update CLOB only of plug-in instance that triggered the change event.

JavaScript Initialization Code

The action uses page item attribute to define optional success and failure callbacks. The attribute must implement anonymous JavaScript function returning JSON object containing done and fail properties defining success and failure JavaScript callback.s

See the example code below:

function( pOptions ) {
  pOptions.done = function( pItemName, pChecksum ){
    // JavaScript Code to be executed after successful updating rich text document in APEX and the plug-in session state
    // @pItemName - page item that was updated using the action
    // @pChecksum - CLOB checksum after updating in the plug-in session state as draft CLOB
  };
  
  pOptions.fail = function( pItemName, pAjaxResult ){
    // JavaScript Code to be executed when updating rich text document fails, for example when an application session expires
    // @pItemName - page item that was updated using the action
    // @pAjaxResult - JSON object containg standard AJAX failure arguments: jqXHR, textStatus, errorThrown
  };
    
  return pOptions;
}

---

Image Browser Parameters

The action allows overriding RESTful service handler query parameters used to display images in the Froala Image Browser. A developer has to specify dynamic action attribute Function Returning JSON returning Froala imageManagerLoadParams.

The anonymous function is executed before opening the Froala image browser. The returned custom query parameters are available in the plug-in RESTful service handler browsing images through PL/SQL bind variables.

Example

The sample application example page Image Browse Parameters implements dynamic action returning folder query parameter used by the sample RESTful service browseFolder handler.

The dynamic action implements the following anonymous function

function( pParams ) {
  pParams.folder = apex.item('P1210_UPLOAD_FOLDER').getValue();
  return pParams;
}

The example browseFolder handler implements the following PL/SQL code:

begin  
  UC_FROALA_SAMPLE_REST.imageBrowseFolder(  
    p_session_id      => :sessionId,  
    p_access_token    => :accessToken,
    p_app_user        => :appUser,
    p_application_id  => :applicationId,
    p_page_id         => :pageId,
    p_folder          => :folder,
    p_status          => :status
  );  
end;  

The PL/SQL bind variable :folder is used to fetch and display images from the sample table UC_FROALA_SAMPLE_BLOBS based on folder query parameter value.

---

Upload Parameters

The action allows overriding RESTful service handler query parameters used to upload an image. A developer has to specify dynamic action attribute Function Returning JSON returning Froala imageUploadParams.

The anonymous function is executed before each image is uploaded. The returned custom query parameters are then available in the plug-in RESTful service handler uploading image through PL/SQL bind variables.

Example

The sample application example page Image Upload Parameters implements dynamic action returning folder query parameter used by the sample RESTful service uploadFolder handler.

The dynamic action implements the following anonymous function

function( pUploadParams ) {
  pUploadParams.folder = apex.item('P1220_UPLOAD_FOLDER').getValue();

  return pUploadParams;  
}

The example uploadFolder handler implements the following PL/SQL code:

begin  
  UC_FROALA_SAMPLE_REST.imageUploadFolder(  
    p_access_token   => :accessToken,  
    p_session_id     => :sessionId,  
    p_application_id => :applicationId,  
    p_page_id        => :pageId,  
    p_app_user       => :appUser,  
    p_image_temp_id  => :tempUniqueId,
    p_image_name     => :filename,  
    p_image_content  => :body,  
    p_image_mimetype => :content_type,
    p_folder         => :folder,
    p_status         => :status,  
    p_location       => :location  
  );    
end;

The PL/SQL bind variable :folder is used to save an image in the table UC_FROALA_SAMPLE_BLOBS with column FOLDER set to :folder value.

---

Upload Images on demand

The dynamic action starts uploading images on the end-user demand, for example, when given triggering button is clicked. The difference to default image upload on page submission is the flexibility to handle the plug-in update & upload workflow using JavaScript callbacks.

JavaScript callbacks

Optional callbacks can be defined using the dynamic action attribute Initialization JavaScript Code. A developer has to define an anonymous function returning JSON object containing (optional) callbacks done, cancel and fail.

function(){
  return {
    "done": function(){
      // code to be executed when uploading images is not canceled by the plug-in or the end-user
    },
    "cancel": function(){
      // code to be executed when uploading images is canceled by the plug-in or the end-user
    },
    "fail": function(){
      // code to be executed when uploading images is interrupted by JavaScript error, for example APEX session expires
    }
  }
}

Learn more in Item Plug-in \ Image upload \ update & upload workflow