19.2 Implementing Plug-ins

Create plug-ins to declaratively extend, share, and reuse the built-in types available with Oracle Application Express.

• About Plug-ins
  
• Accessing the Plug-ins Page
  
• Creating a Plug-in
  
• Editing a Plug-in
  
• Adding Custom Attributes to a Plug-in
  
• Uploading Files Associated with a Plug-in
  
• Adding Events to a Plug-in
  
• Deleting a Plug-in
  
• Viewing the Plug-in Repository
  
• Importing a Plug-in from the Plug-in Page
  
• Exporting a Plug-in from the Plug-in Page
  
• Resetting the Plug-in Interactive Report
  
• Viewing Plug-in Utilization Page
  
• Viewing Plug-in History
  

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:

1. Create a plug-in or import a plug-in into your application workspace.

2. Edit or create an authorization scheme, item, region, process, or dynamic action type to use the plug-in.

3. Run your application to test the plug-in.

Viewing Plug-in Examples

You can view plug-in implementation examples in the following locations:

• Go to the Oracle Plug-in Repository.

  See "Viewing the Plug-in Repository."

• Install the sample application, Sample Database Application.

  See "Managing Productivity and Sample Apps in a Full Development Environment" and "Installing and Running Sample Database Application."

• Go to the Oracle Learning Library at http://www.oracle.com/oll/apex. Enter search criteria in the field provided and click Search.

19.2.2 Accessing the Plug-ins Page

To access the Plug-ins page

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. 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

To create a plug-in:

Tip:

To learn more about an attributes described in this section see field-level Help. See "Viewing Field-level Help in Oracle Application Express."

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click Create.

   The Create Plug-in wizard appears.

4. For Create Plug-in, select the method by which you would like to create a plug-in and click Next.
5. Under Name:
   1. Name (Required) - Enter name of the plug-in.
   2. 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.

   3. 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.
   4. Category - Only displays if the selected type is Dynamic Action. Select the category the plug-in is displayed under on the user interface.
6. 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.

7. Under Source:
   1. 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.
   2. 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.
8. 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.

9. Under User Interfaces, select the display devices the App Builder must support for this plug-in. Options include:

   • Desktop

   • Mobile

10. 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.
11. Under Information:
    1. Version - Enter a string to identify the plug-in version.
    2. About URL - Enter a URL to the plug-in authors home page or to additional information about the plug-in.
12. For Help Text, enter help text used by the user to understand how the plug-in works.
13. For Comments, enter comments and notes that never display when the application is running.

    To learn more about each option, see field-level Help.

14. 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.

See Also:

• "Adding Custom Attributes to a Plug-in"

• "Uploading Files Associated with a Plug-in"

• "Adding Events to a Plug-in"

19.2.4 Editing a Plug-in

To edit a plug-in:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click the plug-in you want to edit or view.

   The Plug-in Create/Edit page appears.

4. Make modifications.

   To learn more about each option, see field-level Help.

5. 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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click the plug-in you want to modify.

   The Plug-in Create/Edit page appears.

4. 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 On, Application Express automatically replaces substitution syntax with their actual values.

     If set to Off, 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.

5. 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.

6. 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.

• Uploading a File to Associate with a Plug-in
  
• Automatically Loading CSS and JavaScript Files
  

19.2.6.1 Uploading a File to Associate with a Plug-in

To upload a file:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Select the plug-in.

   The Plug-in Create/Edit page appears.

4. 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.

5. To upload a file:
   1. Click Upload File.
   2. Browse to and select the file you want to upload.
   3. Click Upload.

      The Create/Edit page appears. The name of the uploaded file appears under Files.

6. 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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Select the plug-in.

   The Plug-in Create/Edit page appears.

4. Under File URLs to Load:
   1. Cascading Style Sheet - Enter Cascading Style Sheet file URLs to be loaded with this plug-in.
   2. 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.

5. 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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click the plug-in you want to edit.

   The Plug-in Create/Edit page appears

4. Under Events and click Add Event.

   A new row displays under Events.

5. Under Events:
   1. Name - The display name under which the plug-in event appears in the dynamic action, for example: Start Slide.
   2. Internal Name - The name of the assigned JavaScript event that triggers the dynamic action, for example: slidestart.
6. Click Add Event.
7. Repeat steps 3 through 4 to add another event.
8. Click Apply Changes.

See Also:

"Accessing the Plug-ins Page"

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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click the plug-in you want to delete.

   The Plug-in Create/Edit page appears.

4. Click Delete.
5. 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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. 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.

To import a plug-in:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click Import.

   The import Plug-in page appears.

4. For Specify File:
   1. Import file - Enter or browse to the name of the import file.
   2. File Type - Select Plug-in.
   3. File Character Set - Select the import file character set encoding.
   4. Click Next.
5. For File Import Confirmation, click Next.
6. For Install, click Install Plug-in.

See Also:

"Importing Plug-ins"

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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Under Tasks, click Export Plug-in.

   The Export Plug-in page appears.

4. On the Export Plug-in page:
   1. Application - Select the application to export the plug-in from.
   2. Plug-in - Select plug-in.
   3. File Format - Select file format of the plug-in export.
   4. Click Export
5. Click Export.

   A downloads complete message appears.

See Also:

"Exporting Plug-ins"

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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. 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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. 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:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, click Plug-ins.
3. Click History.

   The History page appears.