Table of Contents
- 1 Table of Contents
- 2 Introduction
- 3 Requirements
- 4 The Plug-in
- 4.1 Default Action
- 4.2 Override Default Action
- 4.3 Context Menu
- 4.4 Attributes
- 4.5 Help in the Page Designer
- 4.6 Events
- 4.7 Event data
- 4.8 Customization
- 4.9 Translations
- 5 Usage Guide
- 6 Sample Application
Fill a gap in the interactive grid and enhance it with the ability to download and preview files!
Features at Glance
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.
Interactive Grid Download File Pro components that are visible to end-user can be easily translated using APEX translation texts.
The table below describes the requirements that were used to define the plug-in’s scope.
The plug-in Download File Pro
The plug-in should allow the downloading of blob files based on given table specification from an Oracle APEX interactive grid.
The plug-in, based on attributes, transfers BLOB content into the user’s browser and initializes the download process.
The plug-in should allow previewing of images, HTML, and PDF files.
The plug-in exposes predefined actions to preview BLOB contents for images, HTML, and PDF files.
The plug-in should expose events allowing a developer to visualize the download process.
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.
The plug-in should be triggered when the specified button is clicked.
The plug-in uses a jQuery selector which allows using buttons, anchors, and other HTML elements to trigger the event.
The plug-in should support a context-menu containing the plug-in actions for the specified button.
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)
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 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.
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.
The default plug-in action, but is also exposed through the context menu.
For jQuery Selector
For Triggering Element
For Event Source
Affected Element Required
Check "Fire on Initialization"
Has "Stop Execution on Error" Attribute
Has "Wait For Result" Attribute
These attributes are available in page designer for a dynamic action implementing the plug-in.
The table name which stores the BLOB content to be downloaded. The table has to be accessible from the current parsing schema.
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
The primary key column of the table which stores the BLOB content to be downloaded.
IG Column Containing BLOB ID
Mime Type Column
The mime type column from the table which stores the BLOB content to be downloaded.
File Name Column
The filename column from the table which stores the BLOB content to be downloaded.
An attribute defines the behavior of the plug-in.
Available options include:
Context Menu Options
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: menu, items, and context:
This attribute changes the default action after the left mouse button click event is performed on the triggering element.
Available options include:
This code has access to the following dynamic action related attributes:
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.
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:
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.
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:
jQuery reference to the triggering element.
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.
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.
The interactiveGridView interface returned from the getViews interactiveGrid widget method.
The result of the grids widget method getContextRecord.
Record id returned by the model interface using the getRecordId method.
The region interface returned from the execution of apex.region.
Properties of this.data.file are listed in the table below.
Fetched file contents (base64 clob). Result of apex_web_service.blob2clobbase64.
BLOB file id.
Fetched file name with extension.
Fetched file size in bytes.
Fetched file mime type.
Properties of this.data.fn are listed in the table below.
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.
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.
Function opening the file contents in a new browser tab.
Function opening an image or file preview in an inline popup.
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)
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.
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.
Context menu "Download" action
Context menu "Open in new tab" action
Open in new tab
Context menu "Preview file" action
Title for the close button in preview inline dialog.
Download anchor text "Download file" in the preview of an image or file
Title for the download link in preview inline dialog.
Message "File preview not available" in an inline popup when the preview for the file type is not available
File preview not available
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.
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:
Content of a file
The mime type of a file
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:
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
In page designer, right-click on Columns in the interactive grid
Click Create Column
For the newly created column:
Set Identification \ Column Name to DOWNLOAD
Set Identification \ Type to Link
Set Heading \ Heading to Download
In the Link section, click on the button No Link Defined
In the popup Link Builder - Target
Set Target \ Type to URL
Apply the changes by clicking OK button
Set Link \ Link Text to Download
Set Link \ Link Attributes to class=”download”
Set Source \ Type to None
Save the page
The newly created column definition in page designer is presented below:
Create new dynamic action called Download file from IG
Set When \ Event to Click
Set When \ Selection Type to jQuery Selector
Set When \ jQuery Selector to .download
Set Advanced \ Event Scope to dynamic
Set Advanced \ Static Container (jQuery Selector) to body
The dynamic action definition in the page designer is presented below:
Dynamic Action - True Action
Change the true action Show to United Codes IG Download File [plug-in]
Set the plug-in attributes
Set Settings \ IG Column Containing BLOB ID to ID
Set Settings \ Table Name to UC_IG_DOWNLOAD
Set Settings \ Primary Key Column to ID
Set Settings \ BLOB Column to FILE_CONTENT
Set Settings \ Mime Type Column to MIME_TYPE
Set Settings \ File Name Column to FILE_NAME
(Optional) Set Settings \ Settings according to your requirements
Set Affected Elements \ Selection Type to Region
Set Affected Elements \ Region to Example
Set Fire on Initialization to No
Save the page
The true action is presented below:
Test the Implementation
Open page 710 in a browser
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.
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:
The overview page describes and shows the plug-in predefined actions.
The events page describes and shows example implementations of the plug-in events.
The customization page describes and shows example customizations that can be done using the plug-in attributes.
The translations page describes and shows an example translation of the plug-in components.