Table Of Contents

About the AOP Modal plug-in

The AOP Modal makes it even easier to download and schedule reports. The AOP Modal gives power to the end-users and allows them to download a Classic Report, Interactive Report, and Interactive Grid in the format and look and feel they want. Easily add a logo and additional text to a template to get the customized output you’ve been waiting for.

Features at Glance

Export an APEX report in different formats

AOP Modal can export reports in the following formats: PDF, Excel (xlsx), Word (docx), HTML, CSV, PowerPoint (pptx), Open Document Text (ODT), Open Document Spreadsheet (ODS), Open Document Presentation (ODP) and Markdown.

Replace the native APEX printing with AOP printing

By checking the checkbox, the native APEX report download and schedule functionality will be replaced by the more powerful AOP Modal.

Classic Report, Interactive Report, and Interactive Grid with pixel-perfect templates

AOP Modal allows the end-user to select a template of their choice without the need for a developer to be involved.

Run in the background

Long-running reports can be easily run in the background, so the end-user doesn’t have to wait for the result.

Schedule

The AOP Modal allows you to schedule reports minutely, hourly, daily, and weekly.

Translatable

AOP Modal components and messages can be easily translated using APEX Text Messages.

Send emails

The AOP Modal can send emails. Bigger reports will be sent as a link with which the recipient can download the file.

Output to the filesystem

The AOP Modal allows you to output the file to a database directory or to the AOP server output directory.

Custom output location

AOP Modal supports the creation of custom post document generation PL/SQL callbacks to handle your reports.

Multiple region sources

AOP Modal can generate a report based on multiple regions in the same document.

Automatic file generation

The AOP Modal can be configured to generate a report without any additional action from the end-user.

Show the download progress

The AOP Modal seamlessly integrates with the Plug-ins Pro Progress Bar to give the end-user an indication of how much longer the generation of the report will take.

Standard Attributes

AOP Modal implements the following standard APEX plug-in attributes:

  • For Region

  • For jQuery Selector

Custom Attributes

AOP Modal exposes attributes to be defined on the APEX page designer level and component level. These attributes are used to configure the plug-in capabilities and settings.

Application

AOP Modal has 6 application attributes which expose general settings used across all application pages.

Attribute Type Default Value Dependent On Description
1 E-mail From Text Not applicable The email address which from which emails are being sent, when the plug-in attribute Output To \ Email is selected.
2 Maximum Attachment Size (KB) Number Not applicable Some email providers don’t allow attachments over a certain size. When the maximum attachment size is reached, instead of attaching the file, a download link is put in the email.
3 Download Link Text Maximum Attachment Size (KB) is not null The download link when the maximum attachment size is reached. Typically this is a public REST endpoint URL.
4 Save Log Yes/No N Not applicable Setting Save Log to Yes enables you to track how the plug-in is used and what downloads have taken place. Every request is stored in the table AOP_DOWNSUBSCR_LOG

Component

The AOP Modal plug-in exposes 12 attributes to be set on the page designer level for dynamic actions which implement the plug-in depending on the plug-in Action attribute.

Summary

In the table below you will see all of the AOP Modal component attributes. Each attribute is described in the sections that follow.

Attribute Type Dependent On
1 Action Select List Not applicable
2 Settings Checkbox Action set to Initialize
3 Report Type Checkbox Action set to Initialize
4 Template Selection Checkbox Action set to Initialize
5 Output To Checkbox Action set to Initialize
6 When Checkbox Action set to Initialize
7 Default Template Checkbox Action set to Initialize
8 Templates (SQL Query) SQL Query Action set to Initialize
9 Tile Text Text Action set to Add a new "Output To" tile
10 Tile Icon Icon Action set to Add a new "Output To" tile
11 Procedure Name Text Action set to Add a new "Output To" tile
12 Initialize PL/SQL Code PL/SQL Code Action set to Initialize
13 Page Item(s) to Submit Page Item(s) Action set to Initialize

Action

This attribute defines the plug-in action when the dynamic action is executed. A dynamic action implementing the plug-in should always implement the Initialize action, which can be optionally followed with true actions implementing the plug-in action Add a new “Output To” tile or Add an Additional Region Source. The Download File (Background) action is a standalone action and should be used to force the download of a generated file after a database job has finished.

Option Description Affected Elements
Initialize Initializes the plug-in based on the Settings, Report Type, Template Selection, Output To, When, Default Template, Templates (SQL Query) and Initialize PL/SQL Code attributes. The dynamic action uses the affected elements to determine which report(s) are enhanced with the AOP Download plug-in.

Learn more about affected elements in the Usage Guide \ Dynamic Action Implementation section.
Add a new "Output To" tile Creates a custom tile in the Output To item . A new Output To tile is created based on the Tile Text and Tile Icon attributes. The Procedure Name attribute is used to handle the file generated by AOP. The action doesn’t use affected elements.
Add an Additional Region Source Adds an additional region source that can be used within the AOP template. Supported region types are Classic Report, Interactive Report and Interactive Grid. The plug-in uses affected elements to clearly identify a region to be included.

Regions must be specified with Affected Elements \ Selection Type set to Region.

Otherwise, and error will be raised:

Action Add Additional Region Source can be combined only with Affected Elements set to Region
Download File (Background) Download the file that was generated by the job referenced in the this.data.jobName dynamic action event data . A job must be finished before this action is called. The action doesn’t use affected elements.

Settings

This attribute defines the plug-in functionalities.

Option Description
Display Message When checked, the plug-in displays the success message depending on the Output To and When values selected by the end-user. The messages can be customized using APEX text messages and the plug-in substitution string.

Learn more about translations and substitution strings in the section The plug-in \ Translations.
Display Spinner When checked, the APEX spinner is displayed while AOP is generating the document.
Hide Native APEX Print When checked, the plug-in removes native print functionalities from Classic Report, Interactive Report and Interactive Grid.

Classic Report - native anchor Print is removed from the footer of a report.

Interactive Report - actions menu entries Download and Subscription are hidden.

* Interactive Grid - actions menu entry Download is hidden.
Enable Save Log When checked, the plug-in enables AOP logging for this instance ignoring the value set on the application level (Component Settings). Otherwise, the value set on application level value is used.
Add AOP JSON in debug mode When checked, the plug-in renders report type AOP JSON when APEX debug mode is enabled irrespectively to selection in the plug-in attribute Report Type.

Report Type

This attribute defines the possible report types which can be generated by the end-user. If only a single value is selected by a developer, then the Report Type item will not not visible in the plug-in dialog (the selected option will be used by default).

The plug-in allows the generation of the following report types:

  • PDF

  • Excel

  • Word

  • HTML

  • CSV

  • PowerPoint

  • Open Document Text

  • Open Document Spreadsheet

  • Open Document Presentation

  • Markdown

  • AOP Template - generates an AOP template based on the given region source

  • AOP JSON - retrieves the JSON that is being sent to the AOP Server. The JSON file is very useful for debugging. If you are sending a support request to the AOP Team, please include this JSON file in your message.

AOP JSON is automatically added to the Report Type dialog item when application debug mode is enabled (independent of the selection in page designer).

Output To

This attribute defines what happens with a generated report. A report can be downloaded to the browser (Browser), inserted into an output table (Table), sent as an attachment via e-mail (E-mail), or saved on the database filesystem (Filesystem DB Directory) or AOP file system (Filesystem AOP Directory).

If only one value is selected by a developer, then the Output To dialog item is not visible (the selected option is used by default).

Handling of the end-user’s selection in the Output to item varies depending on the selection in the When item.

Output To When Description
Browser Now The plug-in initializes the generation of a file and the end-user has to wait for the result. Once the file is generated, it is transferred to the browser for the user to download.
Background The plug-in initializes the generation of a file in the background using a job.
Table Now The plug-in initializes the generation of a file and the end-user has to wait for the result. Once the file is generated, it is inserted into the AOP_DOWNSUBSCR_OUTPUT table.
Background The plug-in initializes the generation of a file in the background using a job. Once the file is generated, it is inserted into the AOP_DOWNSUBSCR_OUTPUT table.
Scheduled The plug-in initializes the generation of a file using a database scheduler job based on the user’s selections. All files generated by this job are inserted into the AOP_DOWNSUBSCR_OUTPUT table.
E-mail Now The plug-in initializes the generation of a file and the end-user has to wait for the result. Once the file is generated,it is sent as an attachment in an e-mail created based on the user’s selections.

The e-mail address of the sender is set to the value given in the E-mail From component attribute.
Background The plug-in initializes the generation of a file in the background using a job. Once the file is generated, it is sent as an attachment in an e-mail created based on the user’s selections.

The e-mail address of the sender is set to the value given in the E-mail From component attribute.
Scheduled The plug-in initializes the generation of a file using a database scheduler job based on the user’s selections. All files generated by this job are sent as an attachment in an e-mail created based on the user’s selections.

The e-mail address of the sender is set to the value given in the E-mail From component attribute.
Filesystem (DB Directory) Now The plug-in initializes the generation of a file and the end-user has to wait for the result. Once the file is generated, it is save in the AOP_DOWNSUBSCR_DIR database directory.

Create the database directory with the following command: CREATE DIRECTORY AOP_DOWNSUBSCR_DIR AS '/home/oracle/aop/';
Background The plug-in initializes the generation of a file in the background using a job. Once the file is generated, it is sent to the AOP_DOWNSUBSCR_DIR database directory.

Create the database directory with the following command: CREATE DIRECTORY AOP_DOWNSUBSCR_DIR AS '/home/oracle/aop/';
Scheduled The plug-in initializes the generation of a file using a database scheduler job based on the user’s selections. All files generated by this job are sent to the AOP_DOWNSUBSCR_DIR database directory.

Create the database directory with the following command: CREATE DIRECTORY AOP_DOWNSUBSCR_DIR AS '/home/oracle/aop/';
Filesystem (AOP Directory) Now The plug-in initializes the generation of a file and the end-user has to wait for the result. Once the file is generated, it is sent to the specified directory on the AOP Server in AOP directory > outputfiles.
Background The plug-in initializes the generation of a file in the background using a job. Once the file is generated, it is sent to the specified directory on the AOP Server in AOP directory > outputfiles.
Scheduled The plug-in initializes the generation of a file using a database scheduler job based on the user’s selections. All files generated by this job are sent to the specified directory on the AOP Server in AOP directory > outputfiles.

When

This attribute defines when file generation should happen. A report can be generated immediately (Now) or by using a database scheduler job - either at a specific point in time or at an interval (Scheduled) or in the background (Background).

If only one value is selected by a developer, then the When dialog item will not be visible to the end-user (the selected option will be used by default).

Option Description
Now File generation starts immediately and the end-user waits for the result. After the file is generated, the plug-in triggers the AOP: Report Generated (Now) event.
Scheduled A file is generated at a specific time as defined by the end-user’s selection:

Starts (Now/On specific date)

Start Date

Repeat Every

Frequency (Minute/Hour/Day/Week/Month/Year)

Days of the week (Mon/Tue/Wed/Thu/Fri/Sat/Sun)


After the plug-in processes the request to create a new scheduled report, the
AOP: Report Generation Scheduled* event is triggered.
Background File generation starts immediately, but the end-user is not forced to wait for the document to finish.

After the plug-in processes the request to create a new job, the AOP: Report Generating in the Background event is triggered.

Template Selection

This attribute describes the possible template types that can be used to generate reports. Template selection is dynamic, dependent on the selected report type. When the report type is changed, the list of available templates is fetched via an AJAX call. If only one template is returned then the Template Selection item is not shown in the dialog (the returned template is used by default).

Option Description
AOP Report The default template used by AOP. AOP generates the report based on the print attributes of the region and any global variables that have been set using Initialize PL/SQL Code attribute.

For example, to set the background color of the heading, specify

aop_api_pkg.g_rpt_header_back_color := '#FF0000';

To learn about other variables read the section The plug-in \ Custom Attributes \ Component \ Initialize PL/SQL Code
APEX Report The default template used by APEX. The report will be generated using the built-in functionality of APEX.
Supported only starting with APEX 20.2.
APEX Report (Data Only) A generated report contains only data. All visual enhancements such as highlighting, grouping etc. is removed.
Template from SQL Query A developer must specify SQL Query returning templates to be picked by the end-user.

Learn more in the The plug-in \ Custom Attributes \ Component \ Templates (SQL Query) section.
Template from AOP Table Templates are fetched from supporting application tables AOP_DOWNSUBSCR_TEMPLATE and AOP_DOWNSUBSCR_TEMPLATE_APP. A developer can’t change the SQL Query but can add/modify existing templates using the supporting application.

Default Template

This attribute describes what the default value of the Choose your template dialog item should be after selecting a new Report Type.

The value of this attribute has to be matched with the value of the Template Selection attribute. Otherwise, the plug-in raises an error.

Option Description
AOP Report AOP Report is selected by default in the plug-in item Choose your template.
APEX Report APEX Report is selected by default in the plug-in item Choose your template.
APEX Report (Data Only) APEX Report (Data Only) is selected by default in the plug-in item Choose your template.
Based on default column A default template is selected from the templates returned by the query defined in Templates (SQL Query) and based on the template_default column.

Learn more about in the Templates (SQL Query) section.

Templates (SQL Query)

This attribute defines what templates can be used by the end-user to generate a report. The SQL Query has to return a specific set of columns: template_id, template_name, template_blob, mime_type and template_default.

Column name Column Type Description
TEMPLATE_ID VARCHAR2 Used to identify the selected template by the end-user.
TEMPLATE_NAME VARCHAR2 The name of the template that is displayed to the end-user in the Template Selection dialog item.
TEMPLATE_BLOB BLOB The BLOB containing the template that will be used to generate a report.
MIME_TYPE VARCHAR2 The MIME type is used to filter the available templates to match the Report Type Selection in the plug-in dialog.

Learn more about templates and report types in the Templates filtered based on a report type section.
TEMPLATE_DEFAULT NUMBER Template default is used to automatically select a template for the selected report type.

By default, the plug-in queries the AOP_DOWNSUBSCR_TEMPLATE table.

select
  to_char(id)       as template_id,
  title             as template_name,
  template_blob     as template_blob,
  mime_type         as mime_type,
  template_default  as template_default  
from
  AOP_DOWNSUBSCR_TEMPLATE

The plug-in extends the query with extra conditions used to filter templates according to report type end-user selection.

Templates filtered based on a report type

When the end-user selects a report type, the plug-in fetches the available templates over an AJAX call. The templates that are returned are filtered based on the selected report type and template mime type.

Report Type Supported Template MIME Types
1 PDF All
2 Excel 1. application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

2. application/vnd.oasis.opendocument.spreadsheet
3 Word 1. application/vnd.openxmlformats-officedocument.wordprocessingml.document

2. application/vnd.oasis.opendocument.text
4 HTML text/html
5 CSV text/csv
6 PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation
7 Open Document Text (ODT) 1. application/vnd.openxmlformats-officedocument.wordprocessingml.document

2. application/vnd.oasis.opendocument.text
8 Open Document Spreadsheet (ODS) 1. application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

2. application/vnd.oasis.opendocument.spreadsheet
9 Open Document Presentation (ODP) application/vnd.openxmlformats-officedocument.presentationml.presentation
10 Markdown text/markdown
11 AOP Template Not applicable.
12 AOP JSON All

Initialize PL/SQL Code

This attribute can be used to define variables used by the AOP to generate a file. The example value might look like below

aop_api_pkg.g_output_filename      := 'output';
aop_api_pkg.g_output_filename      := v('P1_FILENAME');
aop_api_pkg.g_rpt_header_font_size := '12';
aop_api_pkg.g_rpt_header_font_size := '12';
aop_api_pkg.g_prepend_files_sql    := q'[select filename, mime_type, template_blob as file_blob from aop_template where filename like 'PREPEND%' order by filename]';
aop_api_pkg.g_append_files_sql     := q'[select filename, mime_type, template_blob as file_blob from aop_template where filename like 'APPEND%' order by filename]';

The AOP variables are described in the AOP documentation: http://www.apexofficeprint.com/docs/plsql/aop_api20_pkg.html.

Page Item(s) to Submit

This attribute describes a list of page items to be sent along with the AJAX call to generate a report. By default, the plug-in fetches the page item(s) to be sent from the region attribute Source \ Page Items to Submit.

Tile Text

This attribute is available only when the Action attribute is set to Add a new "Output To" tile. The given text is used to set the text of a new tile that will be visible to the end-user.

Tile Icon

This attribute is available only when the Action attribute is set to Add a new "Output To" tile. The given icon is used to set an icon of a new tile that will be visible to the end-user.

Procedure Name

The given procedure is executed when AOP finishes rendering a report and it is used to handle the generated report. The procedure in the database needs to be structured with the parameters listed in the table below. The procedure can be named whatever you like, but the parameters need to match exactly as in the example. You can add other parameters with a default value.

This attribute is available only when Action attribute is set to Add a new "Output To" tile.

Argument Type Description
p_output_blob BLOB The generated report BLOB.
p_output_filename VARCHAR2 The generated report filename.
p_output_mime_type VARCHAR2 The generated report mime type.

An example procedure might look like below.

create procedure send_email_prc(
  p_output_blob      in blob,
  p_output_filename  in varchar2,
  p_output_mime_type in varchar2
) is
  l_id number;
begin
  l_id := apex_mail.send( 
    p_to => 'support@apexofficeprint.com', 
    p_from => 'support@apexofficeprint.com', 
    p_subj => 'Mail from APEX with attachment', 
    p_body => 'Please review the attachment.', 
    p_body_html => 'Please review the attachment.'
  );

  apex_mail.add_attachment( 
    p_mail_id    => l_id, 
    p_attachment => p_output_blob, 
    p_filename   => p_output_filename, 
    p_mime_type  => p_output_mime_type
  );

  commit;    

end send_email_prc;

Initialization JavaScript Code

The plug-in uses dynamic action Initialization JavaScript Code along with the plug-in action Initialize. It allows a developer overriding options used to initialize the plug-in right at the very beginning of the plug-in initialization.

The default value for an attribute is an anonymous JavaScript function accepting only one parameter pOptions. As the result, the function has to return options that will be used to create the plug-in instance.

function( pOptions ) {
  return pOptions;
}

Change dialog title

The plug-in dialog title can overriden with the following JavaScript code

function( pOptions ) {
  pOptions.translate.AOP_DOWNLOAD_DIALOG_TITLE = 'A new title';
  return pOptions;
}

Restrict frequency options

The plug-in schedule frequency item can be restricted to only needed options with the following JavaScript code:

function( pOptions ) {
  //the default array is defined as ['MINUTELY', 'HOURLY', 'DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY'];
  //to show only Minute, Hour and Day change the array as in the example below
  pOptions.frequency = ['MINUTELY', 'HOURLY', 'DAILY'];
  return pOptions;
}

Events

The AOP Modal triggers events along with the plug-in data in order to allow a developer to perform additional actions using the APEX dynamic action interface.

AOP: Before Generating a Report

Event internal name: aopdownloadexecbefore

The event is triggered before the plug-in AJAX call executing a report generation is performed.

Event data

The event is triggered along with the plug-in data available through this.data.

Property Description
this.data.da JSON Object containing information about the dynamic action which implements the plug-in

Learn more about in properties in the The plug-in \ Events \ Dynamic action data section.

AOP: Report Generation

Event internal name: aopdownloadexecsucces

The event is triggered after the plug-in AJAX starting AOP report generation is finished successfully. The plug-in AJAX initializes file generation but it doesn’t mean a requested file is already generated.

Event data

The event is triggered along with the plug-in data available through this.data.

Property Description
this.data.in JSON Object containing all values required to process a report.

Learn more about in properties in the The plug-in \ Events \ The end-user inputs selection section.
this.data.da JSON Object containing information about dynamic action implementing the plug-in

Learn more about in properties in the The plug-in \ Events \ Dynamic action data section.
this.data.content Generated file content encoded in base64.

Available only when the end-user generated a report using:

Output To set to Browser

When set to Now
this.data.fileName Generated file name.

Available only when the end-user generated a report using:

Output To set to Browser

When set to Now
this.data.mimeType Generated file MIME type.

Available only when the end-user generated a report using:

Output To set to Browser

When set to Now
this.data.jobName Job name generating a report.
this.data.subscriptionId The ID of generated report which has been inserted into the AOP_DOWNSUBSCR_OUTPUT table.

Available only when the end-user generated a report using:

Output to is set to Table or E-mail

When set to Now


Otherwise it's set to null

AOP: Report Generation Failed

Event internal name: aopdownloadexecfailure

The event is triggered after the plug-in AJAX starting AOP report generation has failed.

Event data

The event is triggered along with the plug-in data available through this.data.

Property Description
this.data.in JSON Object containing all values required to process a report.

Learn more about in properties in the The plug-in \ Events \ The end-user inputs selection section.
this.data.da JSON Object containing information about dynamic action which implements the plug-in

Learn more about in properties in the The plug-in \ Events \ Dynamic action data section.
info APEX information about the raised error.

AOP: Report Generated (Now)

Event internal name: aopdownloadexecsuccesnow

The event is triggered only when:

  • the plug-in AJAX starting AOP report generation is finished successfully

  • the end-user selected Now in the plug-in When item

Event data

The event is triggered along with the plug-in data available through this.data.

Property Description
this.data.in JSON Object containing all values required to process a report.

Learn more about in properties in the The plug-in \ Events \ The end-user inputs selection section.
this.data.da JSON Object containing information about dynamic action which implements the plug-in

Learn more about in properties in the The plug-in \ Events \ Dynamic action data section
.fileContent The generated report file content encoded in base64.

Available only when the end-user generated a report using Output To set to Browser. Otherwise it's set to null.
fileName The generated report file name.

Available only when the end-user generated a report using Output to is set to Browser, Filesystem (DB Directory) and Filesystem (AOP Directory). Otherwise it's set to null.
mimeType The generated report file mime type.

Available only when the end-user generated a report using Output to is set to Browser, Filesystem (DB Directory) or Filesystem (AOP Directory). Otherwise it's set to null.
subscriptionId The ID of the generated report that has been inserted into the AOP_DOWNSUBSCR_OUTPUT table.

Available only when the end-user generated a report using Output to is set to Table or E-mail. Otherwise it's set to null.

AOP: Report Generation Scheduled

Event internal name: aopdownloadexecsuccescheduled

The event is triggered only when:

  • the plug-in AJAX starting AOP report generation is finished successfully

  • the end-user selected Scheduled in the plug-in When item

Event data

The event is triggered along with the plug-in data available through this.data.

Property Description
this.data.in JSON Object containing all values required to process a report.

Learn more about in properties in the section The plug-in \ Events \ The end-user inputs selection.
this.data.da JSON Object containing information about dynamic action which implements the plug-in

Learn more about in properties in the section The plug-in \ Events \ Dynamic Action data.
this.data.jobName Job name which generates the report.

AOP: Report Generating in the Background

Event internal name: aopdownloadexecsuccesbackground

The event is triggered only when:

  • the plug-in AJAX starting AOP report generation is finished successfully

  • the end-user selected Background in the plug-in When item

Event data

The event is triggered along with the plug-in data available through this.data.

Property Description
this.data.in JSON Object containing all values required to process a report.

Learn more about in properties in the section The plug-in \ Events \ The end-user inputs selection.
this.data.da JSON Object containing information about dynamic action which implements the plug-in

Learn more about in properties in the section The plug-in \ Events \ Dynamic action data
this.data.jobName Job name which generates the report.

Dynamic action data

The event data contains information about a dynamic action which implements the plug-in.

Property Description
this.data.da.id APEX ID of a dynamic action which implements the plug-in instance which triggered the event
this.data.da.name Name of a dynamic action which implements the plug-in instance which triggered the event

The End-user Input Selection

The events are triggered along with the plug-in data this.data.in referencing the end-user selection made in the plug-in dialog.

Property Description
this.data.in.reportType Report type selected by the end-user.

Possible values are:

pdf

xlsx

docx

html

csv

pptx

odt (Open Document Text)

ods (Open Document Spreadsheet)

odp (Open Document Presentation)

md (Markdown)

aop_template (AOP Template)

aop_json (AOP JSON)
this.data.in.reportTemplate Template selected to render the selected report type.

The possible values are the following:

if Choose your template is set to AOP Report then the value is AOP_REPORT

if Choose your template is set to APEX Report then the value is APEX_REPORT

otherwise the value is the ID of a template defined in the AOP_DOWNSUBSCR_TEMPLATE* table
this.data.in.aopTemplate The value of the Generate template item selected by the end-user.

The possible values are:

docx

xlsx

pptx

html

md


This property is available only when the end-user selected
Template in Report Type.*
this.data.in.dataOutput A value of the Output To item selected by the end-user.

The possible values are:

BROWSER

TABLE

EMAIL

FILE_DB_DIR

* FILE_AOP_DIR
this.data.in.when A value of the When item selected by the end-user.
this.data.in.emailTo An e-mail address provided by the end-user in the Email To item.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.emailCc An e-mail address provided by the end-user in the Email CC item.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.emailBcc An e-mail address provided by the end-user in the Email BCC item.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.emailBody An e-mail body provided by the end-user in the Email Body item.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.emailSubject An e-mail subject provided by the end-user in the Email Subject item.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleStarts The value of the Starts item selected by the end-user.

The possible values are:

NOW

DATE


The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleEnds The value of the Ends item selected by the end-user.

The possible values are:

NEVER

DATE


The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleDateStart The value of the Start Date table selected by the end-user. If the Starts item is set to Now then the value is null.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleDateEnd The value of the End Date item selected by the end-user. If the Ends item is set to Never then the value is null.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleRepeatEvery The value of the Repeat Every item selected by the end-user.

The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleRepeatScope The value of the Frequency plug-in item selected by the end-user.

The possible values are:

MINUTELY

HOURLY

DAILY

WEEKLY

MONTHLY

YEARLY


The property is available only when the end-user selected E-mail in Output To.
this.data.in.scheduleRepeatDays The value of the Days of the week item selected by the end-user.

The property is available only when the end-user selected E-mail in Output To.

Translations

AOP Modal components such as dialog item labels, messages, Interactive Report/Interactive Grid menu entry, and Classic Report anchor link are translatable. Translations have to be implemented using Oracle APEX Globalization \ Text Messages. If translations are not defined then the plug-in uses the built-in default values in English.

The plug-in supports overriding text messages on the page designer level. To learn more read the Translations \ Overriding Translations On Page Designer level section.

Messages

The plug-in messages are optionally displayed (the plug-in attribute settings \ Display Message ) after a report is generated, a report starts generating in the background, or a report is scheduled to generate. The message varies depending on the end-user selection in the plug-in dialog (items Output To and When).

Supported Substitution Strings

Every AOP Modal message supports the substitution strings which reference the plug-in dialog item values and values returned from AOP. The availability of a substitution string depends on the end-user’s selection in the Output to and When items.

Substitution String Usage Description
AOP_FILENAME &AOP_FILENAME. Filename of the generated report.

Available only when the end-user set:

Output To to Browswer, Filesystem (DB Directory) or Filesystem (AOP Directory)

When to Now
AOP_MIMETYPE &AOP_MIMETYPE. MIME type of the generated report.

Available only when the end-user set:

Output To to Browswer, Filesystem (DB Directory) or Filesystem (AOP Directory)

When to Now
AOP_JOBNAME &AOP_JOBNAME. Job name responsible for generating a report.

Available only when the end-user set:

When to Background or Scheduled*
AOP_SUBSCRIPTION_ID &AOP_SUBSCRIPTION_ID. The ID of generated report inserted into the AOP_DOWNSUBSCR_OUTPUT table.

Available only when the end-user set:

Output To to Table or E-mail

When to Now
AOP_EMAIL_TO &AOP_EMAIL_TO. The value of the E-mail To item.

Available only when the end-user set Output To to E-mail.
AOP_EMAIL_CC &AOP_EMAIL_CC. The value of the E-mail CC item.

Available only when the end-user set Output To to E-mail.
AOP_EMAIL_BCC &AOP_EMAIL_BCC. The value of the E-mail BCC item.

Available only when the end-user set Output To to E-mail.
AOP_EMAIL_SUBJECT &AOP_EMAIL_SUBJECT. The value of the E-mail Subject item.

Available only when the end-user set Output To to E-mail.
AOP_SCHEDULE_START_DATE &AOP_SCHEDULE_START_DATE. The value of the Start Date item.

Available only when the end-user set Output To to E-mail.
AOP_SCHEDULE_END_DATE &AOP_SCHEDULE_END_DATE. The value of the End Date item.

Available only when the end-user set Output To to E-mail.
AOP_SCHEDULE_REPEAT_EVERY &AOP_SCHEDULE_REPEAT_EVERY. The value of the Repeat Every item.

Available only when the end-user set Output To to E-mail.
AOP_SCHEDULE_SCOPE &AOP_SCHEDULE_SCOPE. The value of the Frequency item.

Available only when the end-user set Output To to E-mail.
AOP_SCHEDULE_DAYS &AOP_SCHEDULE_DAYS. The value of the Days of the week item.

Available only when the end-user set Output To to E-mail.

Supported Text Messages

When a developer specifies the plug-in settings to display a success message (Settings \ Display Message is checked) then, the plug-in displays the message based on a combination of the Output To and When items. These messages can be translated using the APEX Globalization functionality. If no translations are defined, then the plug-in uses the built-in messages presented in the table below.

The messages can be customized per plug-in instance. Learn more in the section The plug-in \ Translations \ Overriding Translations On Page Designer level.

Translation Code Default Text
1 AOP_DOWNLOAD_MSG_BROWSER_NOW File &AOP_FILENAME. generated and downloaded.
2 AOP_DOWNLOAD_MSG_BROWSER_BACKGROUND File is being generating in the background.
3 AOP_DOWNLOAD_MSG_BROWSER_SCHEDULED File has been scheduled.
4 AOP_DOWNLOAD_MSG_TABLE_NOW File saved to table.
5 AOP_DOWNLOAD_MSG_TABLE_SCHEDULED File has been scheduled.
6 AOP_DOWNLOAD_MSG_TABLE_BACKGROUND File is being generating in the background.
7 AOP_DOWNLOAD_MSG_EMAIL_NOW File generated and sent to e-mail "&AOP_EMAIL_TO."
8 AOP_DOWNLOAD_MSG_EMAIL_SCHEDULED File scheduled to be sent to e-mail "&AOP_EMAIL_TO."
9 AOP_DOWNLOAD_MSG_EMAIL_BACKGROUND File will be sent to e-mail "&AOP_EMAIL_TO." when generation has completed.
10 AOP_DOWNLOAD_MSG_FILE_DB_NOW File has been saved to the filesystem (db directory)
11 AOP_DOWNLOAD_MSG_FILE_DB_SCHEDULED File is scheduled to be saved to the filesystem (db directory)
12 AOP_DOWNLOAD_MSG_FILE_DB_BACKGROUND File is being saved to the filesystem (db directory) in the background
13 AOP_DOWNLOAD_MSG_FILE_AOP_NOW File is saved to the filesystem (AOP directory)
14 AOP_DOWNLOAD_MSG_FILE_AOP_SCHEDULED File is scheduled to be saved to the filesystem (AOP directory)
15 AOP_DOWNLOAD_MSG_FILE_AOP_BACKGROUND File is being saved to the filesystem (AOP directory) in the background
16 AOP_DOWNLOAD_MSG_CUSTOM_NOW File generated to custom output location
17 AOP_DOWNLOAD_MSG_CUSTOM_SCHEDULED File is scheduled to generate to custom output location.
18 AOP_DOWNLOAD_MSG_CUSTOM_BACKGROUND File is generating into custom output location in the background

Labels

The plug-in dialog items labels, IR/IG menu entry, and CR link are translatable using APEX Text Messages.

The labels can be customized per plug-in instance. Learn more in the The plug-in \ Translations \ Overriding Translations On Page Designer level section.

Translation Code Default Text
1 AOP_DOWNLOAD_LABEL_MENU_ENTRY AOP Download
2 AOP_DOWNLOAD_LABEL_CR_ANCHOR Print with AOP
3 AOP_DOWNLOAD_LABEL_BUTTON_GENERATE Go
4 AOP_DOWNLOAD_LABEL_BUTTON_CANCEL Cancel
5 AOP_DOWNLOAD_LABEL_ITEM_REPORT_TYPE Report Type
6 AOP_DOWNLOAD_LABEL_ITEM_TEMPLATE_SELECTION Choose your template
7 AOP_DOWNLOAD_LABEL_ITEM_OUTPUTTO Output To
8 AOP_DOWNLOAD_LABEL_ITEM_WHEN When
9 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_STARTS Starts
10 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_STARTS_NOW Now
11 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_STARTS_DATE On specific date
12 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_ENDS Ends
13 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_ENDS_NEVER Never
14 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_ENDS_DATE On specific date
15 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_START_DATE Start Date
16 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_END_DATE End Date
17 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_REPEAT Repeat Every
18 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_SCOPE Frequency
19 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAYS Days of the week:
20 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_MON Mon
21 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_TUE Tue
22 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_WED Wed
23 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_THU Thu
24 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_FRI Fri
25 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_SAT Sat
26 AOP_DOWNLOAD_LABEL_ITEM_SCHEDULE_DAY_SUN Sun
27 AOP_DOWNLOAD_LABEL_ITEM_EMAIL_TO E-mail To
28 AOP_DOWNLOAD_LABEL_ITEM_EMAIL_CC E-mail CC
29 AOP_DOWNLOAD_LABEL_ITEM_EMAIL_BCC E-mail BCC
30 AOP_DOWNLOAD_LABEL_ITEM_EMAIL_SUBJECT E-mail Subject
31 AOP_DOWNLOAD_LABEL_ITEM_EMAIL_BODY E-mail Body
32 AOP_DOWNLOAD_LABEL_ITEM_WHEN_NOW Now
33 AOP_DOWNLOAD_LABEL_ITEM_WHEN_SCHEDULED Scheduled
34 AOP_DOWNLOAD_LABEL_ITEM_WHEN_BACKGROUND Background
35 AOP_DOWNLOAD_LABEL_ITEM_OUTPUTTO_BROWSWER Browser
36 AOP_DOWNLOAD_LABEL_ITEM_OUTPUTTO_TABLE Table
37 AOP_DOWNLOAD_LABEL_ITEM_OUTPUTTO_EMAIL E-mail
38 AOP_DOWNLOAD_LABEL_ITEM_OUTPUTTO_FILE_DB Folder
39 AOP_DOWNLOAD_LABEL_ITEM_OUTPUTTO_FILE_AOP Folder
40 AOP_DOWNLOAD_LABEL_ITEM_FREQUENCY_MINUTELY Minute
41 AOP_DOWNLOAD_LABEL_ITEM_FREQUENCY_HOURLY Hour
42 AOP_DOWNLOAD_LABEL_ITEM_FREQUENCY_DAILY Day
43 AOP_DOWNLOAD_LABEL_ITEM_FREQUENCY_WEEKLY Week
44 AOP_DOWNLOAD_LABEL_ITEM_FREQUENCY_MONTHLY Month
45 AOP_DOWNLOAD_LABEL_ITEM_FREQUENCY_YEARLY Year
46 AOP_DOWNLOAD_HELP_ITEM_EMAIL_BODY Use the #DOWNLOAD_LINK# tag in your email to provide the user with a download link instead of an attachment when it's over the maximum size set by a deveoper.
46 AOP_DOWNLOAD_LABEL_ITEM_AOP_TEMPLATE Generate template
47 AOP_DOWNLOAD_LABEL_ITEM_AOP_TPL_DOCX Word (docx)
48 AOP_DOWNLOAD_LABEL_ITEM_AOP_TPL_XLSX Excel (xlsx)
49 AOP_DOWNLOAD_LABEL_ITEM_AOP_TPL_PPTX Powerpoint (pptx)
50 AOP_DOWNLOAD_LABEL_ITEM_AOP_TPL_HTML HTML
51 AOP_DOWNLOAD_LABEL_ITEM_AOP_TPL_MD Markdown
52 AOP_DOWNLOAD_DIALOG_TITLE AOP Download

Overriding translations at the page designer level

Oracle APEX Text Messages are defined per application and can’t be defined per page or per plug-in instance. Because of that, the plug-in takes advantage of the Initialization JavaScript Code attribute of the dynamic action which allows developers to customize translations per plug-in instance.

The translation is done by assigning a new property (text message code) to JSON object translate.

function( pOptions ) {

  pOptions.translate = {
    //static text for menu entry added to interactive grid and interactive report
    "AOP_DOWNLOAD_LABEL_MENU_ENTRY": "Custom menu entry text",
    //dynamic text (based on translations supporting usage in JavaScript context)
    "AOP_DOWNLOAD_LABEL_CR_ANCHOR": apex.lang.getMessage( "CUSTOM_ANCHOR_LINK_TEXT_MESSAGE" );
  };

  return pOptions;
}

Usage Guide

Initialize the AOP Modal

The dynamic action implementation differs depending on the requirement. The plug-in supports the following use-case scenarios:

  • initialize the plug-in on page load (also on APEX global page)

  • initialize the plug-in on button click

  • initialize the plug-in on jQuery Selector click

Generating a report without the end-user selection in the plug-in dialog

The plug-in supports generating a report without any selection from the end-user. In order to make it work, a developer has to select the unambiguous combination of the following plug-in attributes:

  • Report Type - one option checked

  • Output To - one option checked

  • When - one option checked

  • Template Selection - one option checked

  • Default Template set to value matching selection in Template Selection

Example implementation steps (Page Load)

Implementation steps use presumptions:

  • Interactive Report “Example Report” is created

In order to generate a report without the plug-in dialog follow these steps:

  1. Create a new dynamic action

    1. set Identification \ Name to AOP Download on Page Load

    2. set When \ Event to Page Load

  2. Change default action Show to United Codes AOP Download [Plug-in]

    1. set Action to Initialize

    2. (optional) set Settings

    3. select only one Report Type

    4. select only one Output To

    5. select only one When

    6. select only one Template Selection

  3. Set Affected Elements to Region

    1. set Selection Type to Region

    2. set Region to Example Report

  4. (Alternative) Set Affected Elements to jQuery Selector

    1. set Selection Type to jQuery Selector

    2. set jQuery Selector to .exportWithAop

    3. set interactive report attribute Appearance \ CSS Classes to exportWithAop

Example implementation steps (Button Click)

Implementation steps use presumptions:

  • button BTN_AOP_EXPORT is created

  • Interactive Report “Example Report” is created

In order to generate a report without the AOP Download Modal dialog follow these steps:

  1. Create a new dynamic action

    1. set Identification \ Name to AOP Download on Button Click

    2. set When \ Event to Click

    3. set When \ Button to BTN_AOP_EXPORT

  2. Change default action Show to United Codes AOP Download [Plug-in]

    1. set Action to Initialize

    2. (optional) set Settings

    3. select only one Report Type

    4. select only one Output To

    5. select only one When

    6. select only one Template Selection

  3. Set Affected Elements to Region

    1. set Selection Type to Region

    2. set Region to Example Report

  4. (Alternative) Set Affected Elements to jQuery Selector

    1. set Selection Type to jQuery Selector

    2. set jQuery Selector to .exportWithAop

    3. set interactive report attribute Appearance \ CSS Classes to exportWithAop

Page Load

Typical use-case scenario to implement the AOP Modal for an Interactive Report, Interactive Grid, and Classic Report. A developer has to create a dynamic action which executes on event Page Load. Using the dynamic action affected elements, a developer decides what reports will be enhanced with the AOP Modal. After initialization, the plug-in adds a new entry to an interactive report and interactive grid Actions menu. For classic reports, the plug-in adds a link below a report.

A developer can specify one APEX region using the affected elements (selection type set to Region), or reference multiple APEX regions using selection type set to jQuery Selector.

Affected Elements Region

The plug-in is bound only to the given region.

Affected Elements jQuery Selector

The plug-in is bound to all regions matching the given jQuery Selector. For each region, a new instance of the plug-in is created based on the given configuration in the initialization dynamic action.

This approach can be used on the APEX global page to initialize the plug-in for all regions (matching jQuery Selector) across all application pages.

Example implementation steps

Implementation steps use presumptions:

  • Interactive Report “Example Report” is created

In order to integrate the plug-in with Interactive Report follow these steps:

  1. Create a new dynamic action

    1. set Identification \ Name to AOP Download on Page Load

    2. set When \ Event to Page Load

  2. Change the default Show action to United Codes AOP Download [Plug-in]

    1. set the plug-in configuration using the plug-in attributes
  3. Set Affected Elements to Region

    1. set Selection Type to Region

    2. set Region to Example Report

  4. (Alternative) Set Affected Elements to jQuery Selector

    1. set Selection Type to jQuery Selector

    2. set jQuery Selector to .exportWithAop
      native APEX classes for Interactive Reports “a-IRR” or Interactive Grids “a-IG” can be used

    3. set interactive report attribute Appearance \ CSS Classes to exportWithAop

On button click

The plug-in can be initialized on button click with affected elements referencing only one region (jQuery selector or region selected from a list).

Example implementation steps (Interactive Report)

Implementation steps use presumptions:

  • Interactive Report “Example Report” is created

  • button BTN_AOP_EXPORT is created

In order to integrate the plug-in with Interactive Report follow these steps:

  1. Create a new dynamic action

    1. set Identification \ Name to AOP Download (Interactive Report)

    2. set When \ Event to Click

    3. set When \ Selection Type to Button

    4. set When \ Button to BTN_AOP_EXPORT

  2. Change default Show action to United Codes AOP Download [Plug-in]

    1. set the plug-in configuration using the plug-in attributes
  3. Set Affected Elements to Region

    1. set Selection Type to Region

    2. set Region to Example Report

  4. (Alternative) Set Affected Elements to jQuery Selector

    1. set Selection Type to jQuery Selector

    2. set jQuery Selector to #ir (jQuery Selector has to return only one element)

    3. set interactive report attribute Advanced \ Static ID to ir

Example implementation steps (hidden Classic Report)

Implementation steps use presumptions:

  • Classic Report “Example Report” is created (with Server-side Condition set to Never)

  • button BTN_AOP_EXPORT is created

In order to integrate the plug-in with hidden classic report follow these steps:

  1. Create a new dynamic action

    1. set Identification \ Name to AOP Download (Hidden Classic Report)

    2. set When \ Event to Click

    3. set When \ Selection Type to Button

    4. set When \ Button to BTN_AOP_EXPORT

  2. Change default Show action to United Codes AOP Download [Plug-in]

    1. set the plug-in configuration using the plug-in attributes
  3. Set Affected Elements to Region

    1. set Selection Type to Region

    2. set Region to Example Report

Click on jQuery Selector

The plug-in can be initialized with a click event on jQuery Selector. This use case can be used to generate a document from APEX reports rows based on the data delivered from the hidden classic report source defined on the same page.

Example implementation steps (Interactive Report column)

Implementation steps use presumptions:

  • example page uses ID 1

  • Interactive Report Example IR Report is created

    • the report contains column PRINT with the following settings

      • Identification \ Type is set to Link

      • Link \ Target is set to javascript: void(0);

      • Link \ Link Text is set to

      • Link \ Link Attributes is set to class=”aopprint”

    • the report contains a column ID identifying a row

    • the report has child APEX hidden item P1_ID (not protected)

  • button BTN_AOP_EXPORT is created

  • a hidden classic report Example CR Report is created

    • the report data is filtered using APEX item P1_ID

    • classic report attribute Page Items to Submit is set to P1_ID

In order to integrate the plug-in with Interactive Report column PRINT anchor follow these steps:

  1. Create a new dynamic action

    1. set Identification \ Name to AOP Download (IR anchor)

    2. set When \ Event to Click

    3. set When \ Selection Type to jQuery Selector

    4. set When \ jQuery Selector to .aopprint

  2. Change default action Show to Set Value

    1. set Settings \ Set Type to JavaScript Expression

    2. set Settings \ JavaScript Expression to $(this.triggeringElement).attr("data-id")

    3. set Affected Elements \ Selection Type Item(s)

    4. set Affected Elements \ Item(s) to P1_ID

  3. Create a new action United Codes AOP Download [Plug-in]

    1. set the plug-in configuration using the plug-in attributes
  4. Set Affected Elements to Region

    1. set Selection Type to Region

    2. set Region to Example CR Report

Add a new “Output To” Tile

This usage guide describes creating a custom output to saving generated reports to APEX collection. Implementation steps use presumptions:

  • dynamic action Example AOP Download implementing the plug-in is created with the following attributes set:

    • Settings is set to Display Message, Display Spinner

    • Report Type is set to PDF, Word, HTML, CSV

    • Output To is set to Browser

    • When is set to Now

    • Template Selection is set to AOP Report

    • Default Template is set to AOP Report

  • procedure aop_outputto_collection is created in the application parsing scheme and is defined as

    ``` create or replace procedure aop_outputto_collection( p_output_blob in blob, p_output_filename in varchar2, p_output_mime_type in varchar2, p_app_id in number default v('APP_ID'), p_page_id in number default v('APP_PAGE_ID'), p_session in number default v('APP_SESSION'), p_debug in varchar2 default v('DEBUG') ) is v_collection_name varchar2(100) := 'OUTPUTTO_COLLECTION'; begin

    if not apex_collection.collection_exists(v_collection_name) then apex_collection.create_or_truncate_collection( v_collection_name ); end if;

    APEX_COLLECTION.ADD_MEMBER ( p_collection_name => v_collection_name, p_c001 => p_output_filename, p_c002 => p_output_mime_type, p_blob001 => p_output_blob );

    end aop_outputto_collection; ```

In order to add a new output to, follow these steps:

  1. Edit dynamic action Example AOP Download

  2. Go to true action implementing the plug-in

    1. set Output To to Browser, Custom Output To
  3. Create a new true action

    1. change default action Show to United Codes AOP Download [Plug-in]

    2. set Action to Add a new “Output To“ tile

    3. set Tile Text to Collection

    4. set Tile Icon to fa-apex

    5. set Procedure Name to aop_outputto_collection

  4. Save and run the page

  5. Test the new output to

Add additional region source

This usage guide describes adding new region sources to be included in the generated report. Implementation steps use presumptions:

  • Classic Report “Example CR” is created

  • Interactive Report “Example IR” is created

  • dynamic action Example AOP Download implementing the plug-in is created with the following attributes set:

    • Settings is set to Display Message, Display Spinner

    • Report Type is set to PDF, Excel, Word, HTML

    • Output To is set to Browser, Table, E-mail

    • When is set to Now, Scheduled, Background

    • Template Selection is set to AOP Report

    • Default Template is set to AOP Report

    • Affected Elements references classic report Example CR

In order to add a new region source (interactive report Example IR), follow these steps:

  1. Edit dynamic action Example AOP Download

  2. Go to true action implementing the plug-in

  3. Create a new true action

    1. change default action Show to United Codes AOP Download [Plug-in]

    2. set Action to Add an Additional Region Source

    3. set Affected Elements \ Selection Type to Region

    4. set Affected Elements \ Region to Example IR

  4. Save and run the page

  5. Test the plug-in