Project: Plug-ins-Plus : Interactive Grid File Download Pro

Table of Contents

Introduction

Fill a gap in the interactive grid and enhance it with the ability to download and preview files!

With the Interactive Grid File Download Pro plug-in, you don't have to write custom JavaScript and PL/SQL code to fetch and download files directly from the grid. A simple dynamic action plug-in provides an easy way to deal with BLOB files - just as easy as it is in a classic report.

Features at Glance

Predefined Actions

Interactive Grid Download File Pro exposes predefined actions such as file download, file preview, and open in a new tab using the APEX popup menu.

Translatable

Interactive Grid Download File Pro components that are visible to end-user can be easily translated using APEX translation texts.

Customizable

Interactive Grid Download File Pro components and behavior can be customized with JavaScript in the context of the BLOB file.

Requirements

The table below describes the requirements that were used to define the plug-in’s scope.

Requirement

The plug-in Download File Pro

1

The plug-in should allow the downloading of blob files based on given table specification from an Oracle APEX interactive grid.

(tick)

The plug-in, based on attributes, transfers BLOB content into the user’s browser and initializes the download process.

2

The plug-in should allow previewing of images, HTML, and PDF files.

(tick)

The plug-in exposes predefined actions to preview BLOB contents for images, HTML, and PDF files.

3

The plug-in should expose events allowing a developer to visualize the download process.

(tick)

The plug-in exposes several events that can be used to visualize the AJAX processes for fetching file information and transferring the file to the end-user’s browser.

4

The plug-in should be triggered when the specified button is clicked.

(tick)

The plug-in uses a jQuery selector which allows using buttons, anchors, and other HTML elements to trigger the event.

5

The plug-in should support a context-menu containing the plug-in actions for the specified button.

(tick)

The plug-in supports a context-menu built on top of the native APEX popup menu.

The menu is accessible through the right-click event (context -menu)

6

The plug-in should support custom JavaScript callbacks to be defined by a developer.

(tick)

The plug-in supports customizing context-menu entries using JavaScript code, creating callbacks on the plug-in events, and overriding default actions.

The Plug-in

Default Action

The main purpose of the plug-in is to allow end-users to download a BLOB file from within an Interactive Grid. The default behavior (click on anchor) downloads file content. The process behind the scene fetches the blob file from the database, encodes it into a base64 CLOB, and returns it to the end-user's browser using an AJAX call. Immediately after the AJAX call is completed, the plug-in initializes the download process in the browser.

Override Default Action

The plug-in allows you to change the default action (left mouse click on download anchor) using the plug-in Settings \ Change Default Action and Custom Action attributes. Using these settings, the default behavior can be changed to open the context menupreview the fileopen the file in a new tab, or to execute developer-defined JavaScript code in the context of the file.

Context Menu

The plug-in uses a context-menu to expose other functionality such as Preview and Open in new Tab. The plug-in context-menu entries can be translated, customized, and extended.

Preview

The fetched BLOB file can be previewed if it its type is an image or its content can be displayed in an iframe. Images are presented in an inline overlay preview with a download link. Files such as pdf, HTML, and xHTML can be previewed in an inline preview, but they are embedded in an iframe. Other files, ie. excel spreadsheets can't be previewed directly in the browser. These files use common inline dialogs with information that a preview is not available and users can download the file using the download link.

Open in a New Tab

The fetched BLOB file is opened in a new browser tab embedded in the new iframe element.

Download

The default plug-in action, but is also exposed through the context menu.

Attributes

Standard

Attribute

Supported

For Item(s)

(error)

For Button

(error)

For Region

(tick)

For jQuery Selector

(error)

For JavaScript Expression

(error)

For Triggering Element

(error)

For Event Source

(error)

Affected Element Required

(tick)

Check "Fire on Initialization"

(error)

Has "Stop Execution on Error" Attribute

(error)

Has "Wait For Result" Attribute

(error)

Has "Initialization JavaScript Code" Attribute

(error)

Custom

These attributes are available in page designer for a dynamic action implementing the plug-in.

Attribute

Dependent on

Type

Description

Table Name

Not Applicable

Text

The table name which stores the BLOB content to be downloaded. The table has to be accessible from the current parsing schema.

BLOB Column

Not Applicable

Text

BLOB column from the table which stores the BLOB content. If the specified column type is not a BLOB, an error is raised when the page loads the plug-in.

Primary Key Column

Not Applicable

Text

The primary key column of the table which stores the BLOB content to be downloaded.

IG Column Containing BLOB ID

Not Applicable

Text

The column name in the interactive grid that stores BLOB primary key. This column doesn't have to be visible but must be accessible trough the interactive grid JavaScript API.

Mime Type Column

Not Applicable

Text

The mime type column from the table which stores the BLOB content to be downloaded.

File Name Column

Not Applicable

Text

The filename column from the table which stores the BLOB content to be downloaded.

Settings

Not Applicable

Checkboxes

An attribute defines the behavior of the plug-in.

Available options include:

  • Download When Ready

    • When checked, the plug-in initializes browser download of the file, immediately after the file is transferred from the database to the end-user's browser.

    • When not checked, the plug-in fetches and stores the file contents and details but does not initialize the browser download. To download the file you need to define a dynamic action for the  File Download - file is ready event.

  • Context Menu

    • When checked, the plug-in enables context-menu with predefined actions. The context-menu is invoked after a right mouse click on the triggering element.

    • When not checked, the plug-in doesn't override the default browser action for a right mouse click on the triggering element.
      See help text for attribute Context Menu Options to learn more about customizing the plug-in context-menu.

  • Change Default Action

    • When checked, the plug-in allows overriding of the default action (left mouse button) on the triggering element.

    • When not checked, the plug-in uses the default action (download file) when end-user clicks (left mouse button) on the triggering element.
      See help text for attributes Default Action and Custom Action to learn more about changing the default action.

Context Menu Options

Settings

JavaScript Code

This attribute allows you to customize the plug-in context menu in the context of the file to be downloaded. The valid attribute value is an anonymous function returning an array of APEX menu.Item objects.

The function accepts three parameters: menuitems, and context:

  • menu
    A jQuery reference to the DOM object that is used as the container for the plug-in context-menu. Use it to reference existing context-menu entries.

  • items
    An array of menu.Item objects describing the APEX menu widget entry. Read the official documentation for APEX popup menu items to learn more.
    https://docs.oracle.com/en/database/oracle/application-express/19.2/aexjs/menu.html#.Item

  • context
    A JSON object containing information about the plug-in methods, file to be downloaded, triggering element, and interactive grid.

Default Action

Settings

Select List

This attribute changes the default action after the left mouse button click event is performed on the triggering element.

Available options include:

  • Context Menu
    When selected, the plug-in’s default action opens the plug-in context menu.

  • Open In New Tab
    When selected, the plug-in’s default action is Open in a new tab. The file contents is embedded in an iframe. If the browser supports previewing the file (based on type) it can be previewed directly in the browser. Otherwise, the file is downloaded in a new tab.

  • Preview
    When selected, the plug-in’s default action is Preview. The file contents is embedded in an inline dialog with the ability to download the file. If previewing the file is not possible then the inline dialog contains information that file can't be previewed.

  • Custom Action
    When selected, the plug-in default action is defined by custom JavaScript code defined in the Custom Action attribute.

Custom Action

Default Action

JavaScript Code

This code has access to the following dynamic action related attributes:

  • this.triggeringElement
    A reference to the DOM object of the element that triggered the dynamic action.

  • this.affectedElements
    A jQuery object containing all the affected elements.

  • this.action
    The action object containing details such as the action name and additional attribute values.

  • this.browserEvent
    The event object that triggered the event. Note: On load, equals 'load'.

  • this.data
    Optional additional data that can be passed from the event handler.

This code also has access to the triggering element, interactive grid, and plug-in methods. To fetch a file’s contents use exposed functions via this.data.fn.download.

  • this.data.element
    jQuery reference to the triggering element.

  • this.data.fn
    An object containing references to exposed plug-in functions that fetch the file using AJAX.

  • this.data.fn.download( pCallback ) Returns Promise
    When the file is transferred (AJAX call ends) it executes the callback function passed as the argument.

    A callback function is executed with the overridden function context (this). Within the function body, you can use the this variable to reference a JSON object the same as this.data described in this inline help. Additionally, you can reference a file’s contents using this.file.content.

  • this.data.fn.downloadandsave Returns Promise
    When the file is transferred (AJAX call ends) it automatically downloads the file.

  • this.data.fn.newtab Returns Promise
    When the file is transferred (AJAX call ends) it automatically opens the file in a new tab.

  • this.data.fn.preview Returns Promise
    When the file is transferred (AJAX call ends) it automatically opens the file preview.

  • this.data.fn.savefile Returns Object describing the file (name, size, type, and content)
    This function downloads the file. The function should be used when you are certain that the file has been already transferred to the end-user’s browser. If the file is not yet available the plug-in raises an error.

  • this.data.grid
    The interactiveGridView interface returned from the getViews interactiveGrid widget method.

  • this.data.record
    The result of the grids widget method getContextRecord.

  • this.data.recordId
    Record id returned by the model interface using the getRecordId method.

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 plug-in Settings \ Context Menu Options attribute is presented below:

Events

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

File Download - download started 

The event is triggered when downloading the contents of a BLOB begins. This event has access to general information about the triggering element and interactive grid - learn more about the plug-in event data in the  Event data section.

File Download - download ended

The event is triggered when downloading the contents of BLOB ends. This event has access to general information about the triggering element and interactive grid - learn more about the plug-in event data in Event data section.

File Download - file downloaded

The event is triggered when browser download is initialized.

File Download - file is ready

The event is triggered when file contents was successfully fetched from the database and its contents was transferred to the end-user’s browser. This event is triggered only when the plug-in  Download when ready setting is not checked.

File Download - context menu start 

The event is triggered when the plug-in starts fetching information about the file to construct the context menu. Usually, information about the file is fetched immediately but in case of delay, the event can be used to display a loading indicator to end-user to signal the process is running in the background.

File Download - context menu end

The event is triggered when the plug-in finishes fetching information about the file to construct the context menu. The event can be used to hide the loading indicator added with the event File Download - context menu start.

Event data

The plug-in events have access to this.data referencing the plug-in data for the interactive grid, file, and plug-in methods.

Properties of this.data are listed in the table below:

Property

Description

this.data.element

jQuery reference to the triggering element.

this.data.file

An object describing a downloaded file. See the property description in the table below.

Available only for File Download - file is ready and File Download - file downloaded events.

this.data.fn

An object containing references to the plug-in methods. See the property description in the table below.

Available only for File Download - file is ready and File Download - file downloaded events.

this.data.grid

The interactiveGridView interface returned from the getViews interactiveGrid widget method.

this.data.record

The result of the grids widget method getContextRecord.

this.data.recordId

Record id returned by the model interface using the getRecordId method.

this.data.region

The region interface returned from the execution of apex.region.

Properties of this.data.file are listed in the table below.

Property

Description

this.data.file.content

Fetched file contents (base64 clob). Result of apex_web_service.blob2clobbase64.

this.data.file.id

BLOB file id.

this.data.file.name

Fetched file name with extension.

this.data.file.size

Fetched file size in bytes.

this.data.file.type

Fetched file mime type.

Properties of this.data.fn are listed in the table below.

Property

Description

Returns

Arguments

this.data.fn.download

Function initializing the transfer of the file to the end-user’s browser using an AJAX request. When the file is transferred (AJAX call ends) the callback function is executed. The callback function is executed with changed context (this) to an object similar to this.data variable. Additionally, you can reference a file’s contents using this.data.file.content.

Promise

Callback Function

this.data.fn.downloadandsave

Function initializing the transfer of the file to the end-user’s browser using an AJAX request. When the file is transferred (AJAX call ends) it automatically downloads the file.

Promise

None

this.data.fn.newtab

Function opening the file contents in a new browser tab.

Promise

None

this.data.fn.preview

Function opening an image or file preview in an inline popup.

Promise

None

this.data.fn.savefile

Function initializing the download of the file in the end-user’s browser. If the file is not yet available the plug-in raises an error.

An object describing the downloaded file (name, size, type, and content)

None

Customization

The plug-in context menu is implemented using the Oracle APEX menu widget. Customization can be done after selecting the plug-in  Settings \ Context Menu attribute. Using the plug-in Context Menu Options attribute you can add new entries, remove, and change existing entries.

By default, the plug-in exposes four entries. Using the APEX widget API you can easily modify existing entries using the find widget method.

Translations

If needed, the plug-in components visible to the end-user can be translated using Translate \ Text Messages. Context menu entries and anchor text in inline popup preview can be translated using the following text messages.

To make the translations work with the plug-in, ensure that each text message has the Used in JavaScript property set to Yes and application globalization settings is set to fetch current language from the session.

Code

Description

Default Text

UC_IGDOWNLOADFILE_MENU_DOWNLOAD

Context menu "Download" action

Download

UC_IGDOWNLOADFILE_MENU_NEWTAB

Context menu "Open in new tab" action

Open in new tab

UC_IGDOWNLOADFILE_MENU_PREVIEW

Context menu "Preview file" action

Preview File

UC_IGDOWNLOADFILE_PREVIEW_CLOSE_TITLE

Title for the close button in preview inline dialog.

Close preview

UC_IGDOWNLOADFILE_PREVIEW_DOWNLOAD

Download anchor text "Download file" in the preview of an image or file

Download file

UC_IGDOWNLOADFILE_PREVIEW_DOWNLOAD_TITLE

Title for the download link in preview inline dialog.

Download file

UC_IGDOWNLOADFILE_PREVIEW_NOTAVAILABLE

Message "File preview not available" in an inline popup when the preview for the file type is not available

File preview not available

Usage Guide

This section describes an example implementation of Interactive Grid Download File Pro in an example 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 is using the Interactive Grid Download File Pro sample application table, UC_IG_DOWNLOAD. Table columns are described in the table below:

Column Name

Data Type

Description

ID

NUMBER

Primary key

FILE_CONTENT

BLOB

Content of a file

MIME_TYPE

VARCHAR2(100)

The mime type of a file

FILE_NAME

VARCHAR2(50)

The filename of a file

In the example application, page 710 is defined. On the page, an interactive grid region called Example is created and contains three columns:

  • ID

  • MIME_TYPE

  • FILE_NAME

All columns are Display Only and the interactive grid doesn’t support editing. This usage guide will lead you through the process of creating the 4th column which will be using the plug-in to download a file stored in the FILE_CONTENT column.

The initial state of page 710 in page designer is presented below:

The page will look like the following:

Implementing the plug-in

To implement the plug-in you will need to create a new interactive grid column and a dynamic action implementing the plug-in.

Create an interactive grid column

  1. In page designer, right-click on Columns in the interactive grid

  2. Click Create Column

  3. For the newly created column:

    1. Set Identification \ Column Name to DOWNLOAD

    2. Set Identification \ Type to Link

    3. Set Heading \ Heading to Download

    4. In the Link section, click on the button No Link Defined

    5. In the popup Link Builder - Target

      1. Set Target \ Type to URL

      2. Set Target \ URL to javascript: void(0);

      3. Apply the changes by clicking OK button

    6. Set Link \ Link Text to Download

    7. Set Link \ Link Attributes to class=”download”

    8. Set Source \ Type to None

  4. Save the page

The newly created column definition in page designer is presented below:

Dynamic Action

  1. Create new dynamic action called Download file from IG

  2. Set When \ Event to Click

  3. Set When \ Selection Type to jQuery Selector

  4. Set When \ jQuery Selector to .download

  5. Set Advanced \ Event Scope to dynamic

  6. Set Advanced \ Static Container (jQuery Selector) to body

The dynamic action definition in the page designer is presented below:

Dynamic Action - True Action

  1. Change the true action Show to United Codes IG Download File [plug-in]

  2. Set the plug-in attributes

    1. Set Settings \ IG Column Containing BLOB ID to ID

    2. Set Settings \ Table Name to UC_IG_DOWNLOAD

    3. Set Settings \ Primary Key Column to ID

    4. Set Settings \ BLOB Column to FILE_CONTENT

    5. Set Settings \ Mime Type Column to MIME_TYPE

    6. Set Settings \ File Name Column to FILE_NAME

    7. (Optional) Set Settings \ Settings according to your requirements

  3. Set Affected Elements \ Selection Type to Region

  4. Set Affected Elements \ Region to Example

  5. Set Fire on Initialization to No

  6. Save the page

The true action is presented below:

Test the Implementation

  1. Open page 710 in a browser

  2. Click on the Download anchor

Page 710 after adding a new column is presented below. Clicking on the “Download” link will initialize the download process.

Sample Application

The Interactive Grid Download File Pro is delivered with a sample application which describes all of the plug-in’s features with example implementations. The sample application describes and implements the following topics:

Overview

The overview page describes and shows the plug-in predefined actions.

Events

The events page describes and shows example implementations of the plug-in events.

Customization

The customization page describes and shows example customizations that can be done using the plug-in attributes.

Translations

The translations page describes and shows an example translation of the plug-in components.