221/292
19.2 Implementing Plug-ins
Create plug-ins to declaratively extend, share, and reuse the built-in types available with Oracle Application Express.
19.2.1 About Plug-ins
Oracle Application Express supports a set group of authentication scheme, authorization scheme, item, region, dynamic action, and process types. Plug-ins offer a means of augmenting these built-in types by declaratively creating and using new types in your application. Because plug-ins are designed for reuse, developers can export and import them to other workspaces and also share them with the Oracle Application Express Plug-in community by using the Plug-in Repository.
The process of implementing a plug-in involves the following steps:
-
Create a plug-in or import a plug-in into your application workspace.
-
Edit or create an authorization scheme, item, region, process, or dynamic action type to use the plug-in.
-
Run your application to test the plug-in.
Viewing Plug-in Examples
You can view plug-in implementation examples in the following locations:
19.2.2 Accessing the Plug-ins Page
To access the Plug-ins page
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
The Plug-ins page displays with the Plug-ins tab selected by default. All available plug-ins appear.
You can customize the appearance of the page using the Search bar at the top of the page.
19.2.3 Creating a Plug-in
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click Create.
The Create Plug-in wizard appears.
- For Create Plug-in, select the method by which you would like to create a plug-in and click Next.
- Under Name:
- Name (Required) - Enter name of the plug-in.
- Internal Name (Required) - Enter the internal name of the plug-in. This name must be unique within the current application.
Note:
To insure the internal name is a globally unique name worldwide, Oracle recommends that your organization domain name be used as a prefix to internal plug-in names. For example, a domain name of example.com.com
prefixed to a plug-in named Slider
, would result in an internal name of COM.EXAMPLE.SLIDER
.
- Type (Required) - Select the type of component that can use this plug-in. Depending upon the plug-in type you select, the options under Callbacks and Standard Attributes differ. To learn more, see field-level Help.
- Category - Only displays if the selected type is Dynamic Action. Select the category the plug-in is displayed under on the user interface.
- Under Subscription:
-
Reference Master Plug-in From - To base this plug-in on another plug-in in this workspace, select the plug-in from the list. Otherwise, leave the field blank to make this the master copy of this plug-in.
- Under Source:
- PL/SQL Code - Enter a PL/SQL anonymous block of code that contains the procedures for rendering, validating, executing, and performing Ajax callbacks for this plug-in. For performance reasons you can also store this code in a PL/SQL package in the database.
- Do not validate PL/SQL code (parse PL/SQL code at runtime only) - Select this option to parse the PL/SQL code at runtime only. Otherwise, the code is parsed when the plug-in is created.
- Under Callbacks, configure that appropriate attributes. The attributes that display depend upon the plug-in type. To learn more about an attribute and view examples, see field-level Help.
Tip:
All Callback function names can reference a function of the anonymous PL/SQL code block, a function within a package or a standalone function in the database.
- Under User Interfaces, select the display devices the App Builder must support for this plug-in. Options include:
- For Standard Attributes, select the attributes that apply to this plug-in. Standard Attributes do not display for some plug-ins. To learn more, see field-level Help.
- Under Information:
- Version - Enter a string to identify the plug-in version.
- About URL - Enter a URL to the plug-in authors home page or to additional information about the plug-in.
- For Help Text, enter help text used by the user to understand how the plug-in works.
- For Comments, enter comments and notes that never display when the application is running.
To learn more about each option, see field-level Help.
- Click Create. Plug-in.
Now that the plug-in is created, you can specify additional custom attributes, upload files such as image, CSS and JavaScript files to associate with your plug-in and add events.
19.2.4 Editing a Plug-in
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click the plug-in you want to edit or view.
The Plug-in Create/Edit page appears.
- Make modifications.
To learn more about each option, see field-level Help.
- Click Apply Changes.
19.2.5 Adding Custom Attributes to a Plug-in
Custom Attributes specified by the developer might contain items referenced with substitution syntax.
To add custom attributes to the plug-in:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click the plug-in you want to modify.
The Plug-in Create/Edit page appears.
- Under Custom Attributes, enable or disable the substitution of attribute values.
-
Substitute Attribute Values - Custom attribute values specified by the developer might contain items referenced with substitution syntax, for example &P1_DNAME
.
If set to Yes, Application Express automatically replaces substitution syntax with their actual values.
If set to No, substitution syntax is written unchanged into the attribute_01
through attribute_15
record type attributes of p_plugin
, p_item
, p_region
, and so on. The plug-in developer is responsible for replacing those substitution syntax references with a call to apex_plugin_util.replace_substitutions
or perform similar replacements. See item help for further details.
To learn more, see field-level Help.
- To add an attribute click Add Attribute.
The Edit Attribute page appears. Edit the appropriate attributes.
To learn more about a specific attribute, see field-level Help.
- Click Create to create the attribute and go back to the Edit page, or click Create and Create Another to create the attribute and continue to create another attribute.
Note:
If you click Create or Create and Create Another and the Return To Page check box on the right panel under Plug-ins is checked, this same Edit Attribute page displays.
19.2.6 Uploading Files Associated with a Plug-in
Learns how to upload the files associated with a plug-in.
19.2.6.1 Uploading a File to Associate with a Plug-in
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Select the plug-in.
The Plug-in Create/Edit page appears.
- Locate the Files section.
File Prefix determines the virtual path the Web server uses to point to the files of the plug-in. Do not specify anything to reference files which are stored with your plug-in definition in the database.
- To upload a file:
- Click Upload File.
- Browse to and select the file you want to upload.
- Click Upload.
The Create/Edit page appears. The name of the uploaded file appears under Files.
- Click Apply Changes.
19.2.6.2 Automatically Loading CSS and JavaScript Files
You can have Oracle Application Express automatically load CSS and JavaScript files when a plug-in is used on a page by configuring the File URLs to Load attributes. To specify which of the uploaded files should be loaded and in what order.
To automatically load a CSS or JavaScript file:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Select the plug-in.
The Plug-in Create/Edit page appears.
- Under File URLs to Load:
- Cascading Style Sheet - Enter Cascading Style Sheet file URLs to be loaded with this plug-in.
- JavaScript - Enter JavaScript file URLs for code to be loaded with this plug-in.
You can substitute with the value of the plug-in's file prefix by using substitution string #PLUGIN_FILES#
. For example:
#PLUGIN_FILES#my_plugin.css
To learn more and view examples, see field-level Help.
- Click Apply Changes.
19.2.7 Adding Events to a Plug-in
This section describes how to add events to an item, region, or dynamic action type plug-in, enables them to be exposed to dynamic actions. For example, a Slider plug-in that exposes events such as Start Slide, Sliding, and Stop Slide, allows the creation of dynamic actions that can react when these events occur.
To add events to a plug-in:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click the plug-in you want to edit.
The Plug-in Create/Edit page appears
- Under Events and click Add Event.
A new row displays under Events.
- Under Events:
- Name - The display name under which the plug-in event appears in the dynamic action, for example:
Start Slide
.
- Internal Name - The name of the assigned JavaScript event that triggers the dynamic action, for example:
slidestart
.
- Click Add Event.
- Repeat steps 3 through 4 to add another event.
- Click Apply Changes.
19.2.8 Deleting a Plug-in
You can delete a plug-in if it is not in use. If it is in use, the Delete button does not display.
To delete a plug-in:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click the plug-in you want to delete.
The Plug-in Create/Edit page appears.
- Click Delete.
- To confirm, click OK.
19.2.9 Viewing the Plug-in Repository
The Plug-in Repository provides a central location where developers can share and download plug-ins. The repository is located on the Oracle Technology Network.
To view the Plug-in repository:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click View Plug-in Repository.
The Oracle Application Express Plug-in Repository displays.
19.2.10 Importing a Plug-in from the Plug-in Page
Use this option to import an exported plug-in to your application. Importing a plug-in can be done from the Plug-ins page under Shared Components, as described here, or from the App Builder home page.
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click Import.
The import Plug-in page appears.
- For Specify File:
- Import file - Enter or browse to the name of the import file.
- File Type - Select Plug-in.
- File Character Set - Select the import file character set encoding.
- Click Next.
- For File Import Confirmation, click Next.
- For Install, click Install Plug-in.
19.2.11 Exporting a Plug-in from the Plug-in Page
Use this option to export a plug-in definition to a file. This file can be imported into any APEX application. Exporting a plug-in can be done from the Plug-ins page under Shared Components, as described here, or from the workspace home page.
To export a plug-in from the Plug-in page:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Under Tasks, click Export Plug-in.
The Export Plug-in page appears.
- On the Export Plug-in page:
- Application - Select the application to export the plug-in from.
- Plug-in - Select plug-in.
- File Format - Select file format of the plug-in export.
- Click Export
- Click Export.
A downloads complete message appears.
19.2.12 Resetting the Plug-in Interactive Report
You can reset the plug-in interactive report to clear all current filters applied to the report.
To reset the interactive report:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- On the Plug-ins page, click Reset.
19.2.13 Viewing Plug-in Utilization Page
The Plug-in Utilization page displays which pages, components, and regions use each plug-in.
To view plug-in utilization:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click Utilization.
The Utilization page appears.
19.2.14 Viewing Plug-in History
The Plug-in History page shows the actions taken on each plug-in, the developer that performed the action and the date of each action.
To view plug-in history:
- Navigate to the Shared Components page:
- On the Workspace home page, click App Builder.
- Select an application.
- On the Application home page, click Shared Components.
The Shared Components page appears.
- Under Other Components, click Plug-ins.
- Click History.
The History page appears.