Image Handling
The Rich Text Editor Pro starts tracking images when a page is loaded and the plug-in is successfuly initialized. Right after initialization, the plug-in scans a document HTML for image tag img, recognizes image nature and updates the plug-in collection for image. The plug-in recognizes three types of images:
- base64 image
- image copied from a different website
- image uploaded using the plug-in RESTful service
- Base64 encoded
- Images from WEB
- Images uploaded using REST
An image dragged and dropped from the end-user desktop (or copied from end-user's clipboard) is added to a rich text document as an image encoded with Base64 algorithm. Such images are embedded directly in rich text HTML using the HTML img attribute.
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" />
In computer science, Base64 is a group of binary-to-text encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The term Base64 originates from a specific MIME content transfer encoding. Each Base64 digit represents exactly 6 bits of data. Three 8-bit bytes (i.e., a total of 24 bits) can, therefore, be represented by four 6-bit Base64 digits.
A document CLOB value in the database is unnecessarily large
An image binary representation as base64 embedded in rich text documents implicates the huge size of a CLOB saved in the database.
Including base64 images in e-mails
Most e-mail services doesn't display base64 images embedded directly in the e-mail body.
An image added using it's URL is embedded in a rich text document with original URL. When the plug-in detects such an image, it tries to download it, and upload it using the plug-in RESTful service.
<img src="https://apex.oracle.com/assets/media/images/homepage/dark-hero-screenshot.png?v=1" />
Images hosted outside your organisation can be removed without warning causing rich text documents to display invalid image.
The plug-in recognizes images uploaded with the plug-in RESTful service. Depending on the end-user activity, these images can be duplicated or removed from rich text documents. The supporting process plug-in lets you handle an uploaded image based on the end-user changes in a rich text document. Whenever the end-user uploads a new image or removes an already uploaded image from a rich text document, you can manage the image in the database on page submission.
See an example image HTML uploaded using the plug-in RESTful service
<img src="http://www.united-codes.com/ords/pluginspro_web/ucfroalasamplerest/get/3515" />
Read the section image upload to learn more about uploading images using the plug-in.
Configuration
The plug-in image handling can be configured using dozens JavaScript options allowing customizations fitting most requirements for rich text editors.
Learn more about image customization in the plug-in guidelines.
Image Context Menu
When end-user focuses an image in a rich text document, the image context menu is displayed allowing image formatting with customizable context menu.
The default image context menu includes the following buttons:
- Replace image - replace image using image from desktop, image referenced by URL or with image available in gallery of uploaded images
- Align image - align image to left, center or right
- Image caption - add text caption to image displayed below an image
- Remove image - remove image from document
- Image link - add image anchor
- Display mode - display image inline with text or make an image break text before after image
- Image style - add custom style to image
- Image alternative text - add alternative text to be displayed when an image can't be loaded
- Image size - set image size with fixed values
- In-Document Image Editing - open TOAST UI Image Editor
An image context menu can be customized to expose only desired buttons with required layout.
Image handling
While working with rich text document, an user can add new images (from user's desktop, clipboard or via URL), copy and paste images within rich text document or simply remove redundant images.
Drag and drop image from desktop
By the default the plug-in doesn't upload images immiedietly after images are added/droped into editor allowing continuosly work with document without disturbing a user. If an added image is not referenced by the plug-in RESTful service URL it is translated into base64 encoded image and it's embeded directly into document's HTML.
Adding an image from user's desktop can be achieved using the Froala Insert image feature or simply by dragging and dropping an image from user's desktop. When an image is added or dropped, it is transformed from binary file into image base64 encoded, and then embeded in document's HTML.
The benefit of adding images from user's desktop is possibility to save the image filename after uploading it.
Paste an image from clipboard
When an image is copied to user's clipboard (it's stored in OS memory) it can be pasted directly into the document editor. Image stored in the memory is represented as binary file, thus it is translated to base64 encoded image and embeded directly in document HTML.
Reference an image with URL
Images can be also added into document using an existing image URL. Just copy an image URL, use insert image by URL and the image will be embeded in document with it's original URL. To ensure the image won't disappear in the future, the plug-in attempts to download the image and upload it using RESTful service.
Duplicating images
When an image is already embeded in rich text document it can be selected, copied and pasted within same document. This operation results in copying surrounding image HTML (if defined, ie. image caption) and pasting it in different place in document. While it's not important for base64 encoded images, and images from foreign webistes, it does affects the plug-in capability to remove already uplaoded images using plug-in RESTful service. Learn more in the section Deleting uploaded images.
Removing images
As long as an image is not uploaded using the plug-in RESTful service the plug-in just removes the images from a rich text document. When removed image is already uploaded, the supporting process plug-in can assists a developer to check if an image can be safely removed (an image is not used anywhere else), and deletes it using custom PL/SQL Code.
Deleting uploaded images in the database is described in the section deleting uploaded images in the database.
Image upload
One of the main features of the plug-in is possibility to upload images when Oracle APEX page is submitted with specified submit request, or on the end-user demand using the supporting dynamic action plug-in.
Images are uploaded using the plug-in RESTful handler using parallel AJAX POST request. Uploading images is monitored by the plug-in upload and update workflow.
On page submission
Images can be uploaded on APEX application page submission using the plug-in page item attribute Upload Image(s) on Request(s). When a page is submitted with specified submit request, the plug-in
- cancels current page submission
- starts upload and update workflow
- (on success) re-submits page with original submit request
- (on cancel) let the end-user inspect upload and update workflow issues using the plug-in upload summary
On demand using dynamic action
Images can be uploaded on the end-user demand using the plug-in dynamic action Upload Images on Demand. In contrast to uploading images on page submission, the dynamic action allows definining three JavaScript callbacks to be executed based on update and upload workflow.
Validating an iamge before upload
Before an image can be uploaded it's validated against allowed image mime-types and maximum image filesize. These restrictions can be set using the plug-in JavaScript options for images.
Upload query parameters
An image upload request can be extended with additional data specific for a current document, user or any other meta-data identifying an image. The custom data is added to upload request using query parameters, and it is accessible in REST upload handler via PL/SQL bind variables.
The plug-in uses default query parameters describing an application and the end-user.
The plug-in upload summary
The plug-in upload and update workflow collects upload results and prepares upload summary to be inspected by the end-user. This is very uselful when some images can't be uploaded due to image upload restrictions or PL/SQL errors on REST service level. Using the plug-in upload summary, the end-user can see all issules in popup window and easily jump to the image in a document.
Image browser
The plug-in built-in image browser enables end-users to add already uploaded images or images that are accessible using RESTful service.
Browse query parameters
Defining custom query parameters enables developers to build powerful image browswer listing images uploaded uisng RESTful service or saved in a filesystem (and accessbible through RESTful service),
The plug-in uses default query parameters describing an application and the end-user.
Database handling
The biggest plug-in advantage over the native APEX rich text editor is possibility to:
- process uploaded images on page submission
- handle uploaded images removed from a document
This database image handling must be implemented using the supporting process plug-in and developer's specified PL/SQL Code.
Saving document-image relation
Uploaded images can be easily tracked in the database using custom PL/SQL code executed by the supporting process plug-in. When images are uploaded, the supporting process plug-in uses a developer specified PL/SQL code to iterate over all images uploaded before submitting a page. What is more, whenever an uploaded image is removed from rich text document, the supporting process plug-in allows a developer to execute custom PL/SQL code iterating only over removed images.
Saving document's images in relation to document can be tested in the plug-in public sample application example page.
Deleting uploaded images in the database
When images are already uploaded using the plug-in RESTful service, and they are removed from rich text document, the supporting process plug-in assists a developer to handle theses images on the database level. The supporting process plug-in iterates over removed images, and using developer's specified PL/SQL code processes them, for example deletes removed image from the database.
Uploaded images duplicates
Duplicating an uploaded image results in having two images referenced by the same URL. If one duplicate is removed it doesn't mean that the image can be deleted in the database because document contains other image with same URL. This is different, when all uploaded images with same URL are removed from a document. Then, the supporting process plug-in allows a developer delete the image in the database.
When image can be safely removed
The process plug-in exposes information whether removed image can be safely removed using the plug-in PL/SQL flag. If removed image wasn't copied within same document, the flag indicates that the image can be safely removed. If necessary, a developer can check whether an image isn't used in other rich text documents using custom PL/SQL code.
- Learn more about supporting process plug-in Delete Removed Images.
- Deleting removed uploaded images can be tested in the plug-in public sample application example page.