Plug-ins Pro

 Image Uploader Pro


Table of Contents

Introduction        3

Features at Glance        3

Safe to use        3

Upload natively to different destinations        3

Client side transformations        3

Chunked Upload        3

Theme and behavior customization        3

Custom Events for further dynamic control        4

Specifications        5

Upload and store        5

APEX Collection        5

Custom Table        5

Web service        6

Transform        6

Resize        6

Crop        7

Compress        7

Transformation configuration        7

Watermark        7

Rename        8

Events        8

Custom Attributes        8

Application        8

Component        9

Storage        9

Behaviour        11

Look & Feel        12

Transformation        12

Help in the Page Designer        14


Introduction

Make your Oracle APEX file upload processes more powerful and user friendly while saving time, processing power and bandwidth. With Image Uploader Pro you can optimize the image upload process by manipulating (resizing ,cropping, watermarking and renaming) your media prior to uploading your files to APEX collections, custom tables or even RESTful services. This easy-to-use plug-in fills a gap in APEX regarding BLOB manipulation.

Features at Glance

Safe to Use

Image Uploader Pro is based on the popular Dropzone plug-in and uses no additional external libraries.

Upload Natively to Different Destinations        

The plug-in allows you to natively upload files into APEX collections, giving you full flexibility for further processing or to external web services using nothing more than the client’s browser.  You can even upload to any custom tables, allowing you to define your foreign key field and save post processing time.

Client-side Transformations

Image Uploader Pro supports different client-side transformations:

Chunked Upload

The plug-in supports chunked uploads, splitting the file into smaller parts to work around server  restrictions.

Theme and Behavior Customization

Image Uploader Pro allows you to customize the look & feel of the drop region as well as other behavioral options.

Custom Events for Further Dynamic Control

The plug-in triggers multiple events during the upload process that enable you to further customize or interact with the process.


Specifications

Image Uploader Pro is a region type plug-in for Oracle Application Express (APEX) based on dropzoneJS (ver. 5.7).

Upload and Store

APEX Collection

Image Uploader Pro supports uploading and storing files directly into APEX collections.

In order to implement this functionality, the following settings need to be set:

Attribute Name

Attribute Value

Description

Storage Type

APEX Collection

-

Collection / Table Name

DROPZONE_UPLOAD

Keep the default collection name or change it to any value

Custom Table

Image Uploader Pro supports uploading and storing files directly into a custom table and allows you to define the custom columns where file metadata will be saved.

Furthermore, it supports foreign key column and item definitions. Images will be ready in your table without the need of further metadata manipulation.

In order to have this functionality, the following settings need to be set:

Attribute Name

Example Attribute Value

Description

Storage Type

Custom Table

-

PK Column

ID

Varchar2/Number column where the primary key will be returned. The Primary Key (PK) must be processed with a Before Insert Trigger. The column value is used for after upload processing.

MIME Type Column

MIME_TYPE

Varchar2 column where the MIME type will be saved.

Filename Column

FILENAME

Varchar2 column where the name of the file will be saved.

FK Item

P4_FOREIGN_KEY

Item where the foreign key value is calculated. Values have to be in session state before loading the upload form.

FK Column

FK_ID

Varchar2/Number column where the foreign Key will be saved.

Date Column

CREATED_ON

Optional date field, where the upload date will be saved.

Collection / Table Name

IUP_IMAGES

Name of the destination table where the images will be saved.

BLOB Column

BLOB_CONTENT

BLOB Column where the file contents will be saved.

Web Service

Image Uploader Pro allows you to push your images to a Web Service directly from the client, avoiding database interaction.

In order to have this functionality, the following settings need to be set:

Attribute Name

Attribute Value

Description

Storage Type

Web service

-

Web service parameters

{"url":"https://example.com/upload/image","method":"POST"}

The JSON file with the Web service parameters has to include the following settings:

  • URL: End-point of the web service
  • Method: POST/PUT depending on your web service needs

Transform

Resize

Image Uploader Pro allows you to resize your images prior to upload keeping the image's aspect ratio. To achieve this, either resizeWidth or resizeHeight has to be set to an integer greater than 0.

Setting both parameters, will lead to image cropping.

Crop

Image Uploader Pro allows you to crop your images prior to upload to fit to a desired size. To achieve this, both resizeWidth and resizeHeight has to be set to an integer greater than 0.

Setting only one parameter, will lead to image resizing.

Compress

Besides resizing, Image Uploader Pro allows you to convert and compress your images prior upload. To achieve this, resizeMimeType and/or resizeQuality can be set in the JSON transformation parameters.

Transformation Configuration

In order to transform images prior to upload, a JSON configuration string has to be set.

The plug-in supports:

Watermark

Image Uploader Pro has the capability to embed text into the image prior  to upload and allows you to control the color, size and position of the text.

In order to achieve this, the following parameters need to be set under the watermarking parameters section:

Rename

Image Uploader Pro allows you to define your own renaming function that will be executed on the client-side, during upload.

In order to rename your files prior to upload, a user defined function can be defined  in the Rename Function field. This function gets the file as an argument and can use the file object.

The actual name of the file that gets used during the upload can be accessed through file.upload.filename.

When converting files to JPEG, a rename function is needed to ensure extension consistency.

Events

The plug-in exposes the following custom events:

Event Name

Help

Dropzone File added

DA event that fires when a single file was added to the Dropzone Region (Client-side).

this.data holds the file element, e.g file.name or file.size

Dropzone Chunked File Upload Success (AJAX)

DA event that fires when uploading 1 chunk of a file was successful (Server-side) (Upload Mechanism Chunked)

this.data holds the server response object

Dropzone Chunked File Upload Error (AJAX)

DA event that fires when uploading 1 chunk of a file has an error (Server-side) (Upload Mechanism Chunked)

this.data holds the server response object

Dropzone File Upload Success (AJAX)

DA event that fires when uploading a file was successful (Server-side) (Upload Mechanism Normal)

this.data holds the server response object

Dropzone File Upload Error (AJAX)

DA event that fires when uploading a file has an error (Server-side) (Upload Mechanism Normal)

this.data holds the server response object

Dropzone Upload completed

Called when the upload was either successful or erroneous.

Dropzone max Files exceeded

DA event that fires per file when more files are added to the Dropzone than allowed (Client-side)

this.data the file element, e.g file.name or file.size

Dropzone Total Upload Progress

DA that fires from time to time during upload of all files and returns the total upload progress (Client-side)

this.data holds the totalPercentage element

Dropzone Dragging File over Region

DA that fires when dragging a file over the Dropzone region (Client-side)

Dropzone File Error

DA that fires when processing a file has an error (Client-side)

this.data holds the file element, e.g file.name, file.size or file.errorMessage

Custom Attributes

Application

The plug-in exposes the following attributes with application scope:

Attribute name

Type

Default value

Display Message

Text

Drop files here or click to upload.

Fallback Message

Text

Your browser does not support drag'n'drop file uploads.

File too Big Message

Text

File is too big ({{filesize}}MiB). Max filesize: {{maxFilesize}}MiB.

max. Files Message

Text

You cannot upload more than {{maxFiles}} files.

Remove File Message

Text

Remove file

Cancel Upload Message

Text

Cancel upload

Cancel Upload Confirm Message

Text

Are you sure you want to cancel this upload?

Invalid File Type Message

Text

You can not upload files of this type.

Chunk Size (in KB)

Number

1048576

Component

The plug-in exposes the following attributes with component scope:

Storage

Attribute Name

Attribute Type

Description

Collection / Table Name

Text

Used to define the APEX Collection name or Custom Table name.

Storage Type

Select List

Choose where the uploaded files are saved.

APEX Collection

The APEX collection method should be the easiest. You only have to enter a Collection Name. Data will be saved as follows:

Column c001 => filename

Column c002 => MIME type

Column d001 => date created

Column n001 => random file id

Column blob001 => BLOB of file

The Default Collection name is DROPZONE_UPLOAD.

Custom Table

When using custom table, besides table name, the following column name could be used:

  • Primary Key
  • Foreign Key
  • Filename
  • MIME Type
  • File Content (BLOB)
  • Date

Please note that the Primary Key (PK) must be processed with a Before Insert Trigger or similar.

Web service

The plug-in allows you to upload directly to an external web service.

Filename Column

Text

Column of your custom Table which holds the information for the Filename. Only if Storage Type is set to Custom Table

MIME Type Column

Text

Column of your custom Table which holds the information for the File MIME Type. Only if Storage Type is set to Custom Table

BLOB Column

Text

Column of your custom Table which holds the information for the File Content (BLOB). Only if Storage Type is set to Custom Table

Date Column

Text

Column of your custom Table which holds the information for the File Upload Date. Only if Storage Type is set to Custom Table

PK Column

Text

Primary Key (PK) Column of your custom file Table. The Primary Key (PK) must be processed with a Before Insert Trigger.

FK Column

Text

Column of your custom Table which holds the information for the foreign key. Only if Storage Type is set to Custom Table

FK Item

Page Item

FK item holding the FK value. Items will be read from the session state. It has to be submitted before upload.

Web Service parameters

Textarea

Specify the parameters for the web service call using JSON file.

Behaviour

Attribute Name

Attribute Type

Description

max. File Size in MB

Number

Maximum File Size (Float Number) that is allowed per file. If a file is larger, it will be removed.

max. Files

Number

Maximum number of files that can be uploaded at once.

Accepted File Types

Text

This option allows you to define a list of accepted file types. A comma separated list of MIME types (with Wildcard support) or file extensions: image/*,application/pdf,.psd is required.

By default all file types are allowed.

Upload Mechanism

Select List

Normal: Files are directly uploaded to the DB using a multipart/form-data POST (FormData) request. This method needs no conversion (decode, encode) of strings, thus the final BLOB is already there and can be used.

Chunked: Files are split into chunks (default: 1MB), then each chunk is encoded into base64. This encoded string is then uploaded to the DB, the DB decodes the encoded chunks and builds a final BLOB out of it.

Both methods should work with all web server combinations. Thus no conversion is needed for "normal" uploads, this method is 2x as fast as "chunked". If, somehow, your web server configuration allows no large multipart/form-data requests, go with the "chunked" method.

Clickable

Select List

If true, the Dropzone Region will be clickable. If false, nothing will be clickable and only Drag & Drop is possible.

Copy & Paste support

Select List

Adds support for Copy & Paste of images in modern browsers (like Chrome or Firefox > 50).

Remove Files after upload

Select List

If true, clears all files from the Dropzone Region after uploading has finished.

Delete Files

Select List

Possibility for end users to delete each file that was uploaded to the server.

Only if no Page Refresh has occurred.

Look & Feel

Attribute Name

Attribute Type

Description

Dropzone Style

Select List

UI Style of your Dropzone Region

  • Grey Border
  • Blue Dashed Border
  • Red Dashed Border
  • Grey Dashed Border/Background

Width

Text

Enter the default width of your Dropzone Region. Valid values are px and % data.

Height

Text

Enter the default height of Dropzone Region. Valid values in px.

Show File Previews

Select List

Show preview images for common file types when adding files. Images get displayed with real content. If you want to add more images or others just Copy/Upload the PNG files to the "img" directory. Naming: .png

Transformation

Attribute Name

Attribute Type

Description

Watermark

Textarea

In order to watermark images prior upload, a JSON configuration string has to be defined in this field.

The following attributes are accepted:

  • font: specifies the text style to use when drawing text. This string uses the same syntax as the CSS font specifier.
  • fontColor: specifies the color, gradient, or pattern to use inside shapes. The default style is #000 (black).
  • positionX: x-axis coordinate of the point at which to begin drawing the text, in pixels.
  • positionY: y-axis coordinate of the point at which to begin drawing the text, in pixels.
  • text: string to be embedded

Rename Function (JavaScript)

Textarea

In order to rename your files prior upload, a user defined function can be defined  in this field. This function gets the file as an argument and can use the file object.

The actual name of the file that gets used during the upload can be accessed through file.upload.filename.

When converting files to JPEG, a rename function is needed to change the extension.

Transformation parameters

Textarea

In order to transform images prior to upload, a JSON configuration string has to be set.

The plug-in supports image resizing keeping aspect ratio, image cropping and image conversion and compression.

  • Resize keeping aspect ratio: setting at least one resize attribute (resizeWidth or resizeHeight), will lead to image resizing keeping aspect ratio
  • Resize cropping: setting both resize attributes (resizeWidth and resizeHeight) will lead to image cropping to desired size
  • Convert and compress: setting resizeMimeType to "image/jpeg" and resizeQuality to a decimal between 0 and 1, will lead to image conversion to JPEG and compression to desired rate. A renaming function is required if the source image is not in JPEG format. See renaming function for that.

Help in the Page Designer

The plug-in attributes are exposed along with help text built into the page designer in the Help tab.

Example help for the Settings \ Storage Type plug-in attribute is presented below:


Usage Guide

This section describes an example implementation of the plug-in in an Oracle APEX application. The usage guide shows the basic implementation of the plug-in and doesn’t describe the plug-in attributes.

Introduction

This usage guide helps you create a dropzone region on page 1, that will resize, watermark and rename the images.

Then, will help you add a report to read from the default DROPZONE_UPLOAD collection to check on file upload. The region refresh occurs automatically and it listens to a custom event from the plug-in.

This guide assumes that you are uploading images.

New blank page

Using the Oracle APEX Wizard, create a new blank page.

New Image Uploader Pro region

Drag and drop an Image Uploader Pro region into the content body position.

Set the Title to a desired value, for example: Image Uploader zone.

Navigate to the Attributes of the region and check the following values to support the upload and store to APEX collection process :

In order to resize all the images to 500px width keeping the image’s aspect ratio, set the following value into the Transformation Parameters section: 

{"resizeWidth":"500"}

In order to apply a watermark, set the following example values into the Watermark section: 

{

"font": "22px Arial",

 "fontColor": "#3b8a50",

 "positionX": 5,

 "positionY": 10,

 "text": "Image Uploader PRO"

}

In order to rename all the images, adding a timestamp to the original name, set the following value into the Rename Function (JavaScript) section: 

function (file) {

        let newName = new Date().getTime() + '_' + file.name;

        return newName;

}

Save and run your page to test that the upload and store functionality works as expected.

New view from collection

The easiest way to show images from a collection is to create a view on top of the collection. Doing so, will allow us to use the native Display Image type of column.

In order to create a view, run the following script in SQL Command:

Create view iup_collections as

select

  seq_id,

  c001 as filename,

  c002 as mime_type,

  d001 as last_update_date,

  Blob001

from apex_collections

where collection_name = 'DROPZONE_UPLOAD'

New classic report region

Add a classic report region below the previously added region. Set the Title to a desired value, for example: Collection Report. Set the “Source type” to SQL Query. Use the following query string for the “SQL Query” field:

select

  seq_id,

  filename,

  mime_type,

  last_update_date,

  dbms_lob.getlength(blob001) image

from

  iup_collections;

Click on the “BLOB001” column from the column list and set the type to Display Image. On the BLOB Attributes section, set the following parameters:

TIP: you can set some CSS properties under Page properties > CSS > Inline to ensure nicer image display, for example: td img {max-width:200px;}

Adding dynamic refresh

In order to automatically refresh the collection report, we can add a dynamic action listening to a custom event, triggered by the plug-in.

Add a new dynamic action and set the “When” property as below:

Set a “True” event to refresh the report.

Then run the application, test it and play with it.