19.2 Implementing Plug-ins

Create plug-ins to declaratively extend, share, and reuse the built-in types available in APEX.

• About Plug-ins
  A plug-in is an extension to the built-in types available APEX. Create plug-ins for declarative use of new item, region, process and dynamic action types in your application.
• Example Plug-ins
  View plug-in examples on apex.world and the Oracle APEX GitHub repository.
• Creating a Plug-in
  Create a plug-in by navigating to Shared Components and running the Create Plug-in wizard.
• Editing a Plug-in
  Edit a plug-in by navigating to Shared Components and selecting it on the Plug-ins page.
• Adding Custom Attributes to a Plug-in
  Add Custom Attributes by editing the plug-in.
• Creating a File to Associate with a Plug-in
  Create a file to associate with a plug-in.
• Automatically Loading CSS and JavaScript Files
  Automatically load CSS and JavaScript files when a plug-in is used on a page.
• Adding Events to a Plug-in
  Add events to an item, region, or dynamic action type plug-in, to enable them to be exposed to dynamic actions.
• Deleting a Plug-in
  Delete plug-ins on the Edit page.
• Viewing the Plug-in Repository
  The Plug-in Repository provides a central location where developers can share and download plug-ins.
• Exporting a Plug-in from the Plug-in Page
  Export a plug-in definition to a file.
• Importing a Plug-in from the Plug-in Page
  Import a plug-in definition to a file.
• Resetting the Plug-in Interactive Report
  Reset the plug-in interactive report to clear all current filters applied to the report.
• Viewing Plug-in Utilization Page
  The Plug-in Utilization page displays which pages, components, and regions use each plug-in.
• 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.

19.2.1 About Plug-ins

A plug-in is an extension to the built-in types available APEX. Create plug-ins for declarative use of new item, region, process and dynamic action types in your application.

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

19.2.2 Example Plug-ins

View plug-in examples on apex.world and the Oracle APEX GitHub repository.

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

• Explore APEX World Plug-ins.

• View Sample Plug-in in the Oracle APEX GitHub repository:

  • Go to https://github.com/oracle/apex.

  • Under Branches, select a release, and then Plug-ins.

19.2.3 Creating a Plug-in

Create a plug-in by navigating to Shared Components and running the Create Plug-in wizard.

To create a plug-in:

Tip:

To learn more about an attributes described in this section see field-level Help.

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 - Enter name of the plug-in.
   2. Internal Name - 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 - 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:
   1. Reference Master Plug-in From - Use this option to base this plug-in on an existing plug-in in this application or another application in your workspace.. Otherwise, leave the field blank to make this the master copy of this plug-in.
   2. Subscribe Component Settings -Specifies if the component settings of the plug-in should be refreshed with the component settings of the subscribed plug-in in the master application if the plug-in is getting refreshed.
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. 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. User Interfaces - Select the display devices the App Builder must support for this plug-in. Options include:

   • Desktop

   • Mobile

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

19.2.4 Editing a Plug-in

Edit a plug-in by navigating to Shared Components and selecting it on the Plug-ins page.

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.

   The 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

Add Custom Attributes by editing the 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 Edit page appears.

4. Custom Attributes - Enable or disable the substitution of attribute values.

   Enable or Disable Substitute Attribute Values. Custom Attribute Values specified by the developer may contain items referenced with substitution syntax, for example &P1_DNAME. Options include:

   • On - APEX automatically replaces substitution syntax with their actual values.

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

     To learn more and view examples, 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 then create another one.

Note:

If you click Create or Create and Create Another and the Return To Page checkbox on the right panel under Plug-ins is checked, this same Edit Attribute page displays.

19.2.6 Creating a File to Associate with a Plug-in

Create a file to associate with a plug-in.

To create 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 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. For performance reasons you can also store your plug-in files on your Web Server. Use #APEX_FILES# or any valid URL to reference them.

5. To upload a file, click Create File.
6. On the Create page:
   1. Directory - Enter the name of the directory where the file should be stored. For example, css or css/images.
      If no directory is specified, the file is stored in the root directory.
   2. File Name - If creating a blank file (for example, script.js), enter the name of the file.
   3. Content - If uploading a file, do one of the following:

      • Drag and drop the file to the Content region.

      • Click the Content region and select the file.

   4. Click Create or Create and Create Another.

19.2.7 Automatically Loading CSS and JavaScript Files

Automatically load CSS and JavaScript files when a plug-in is used on a page.

You can have APEX 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 Edit page appears.

4. Locate File URLs to Load:
   1. Cascading Style Sheet - Enter Cascading Style Sheet file URLs to be loaded with this plug-in. Each URL has to be written on a new line.

      If you provide a minified version of your file you can use the substitution string #MIN# to include .min, or #MIN_DIRECTORY# to include minified/ in your file URL for a regular page view, and an empty string if the page is viewed in debug mode. You also have access to the substitution string #PLUGIN_FILES# to substitute with the value of the plug-in's file prefix.

      File URLs you enter here will be emitted within the #APEX_CSS# substitution string in the page template.

      You do not need to include opening or closing link tags, just the file URL.

   2. JavaScript - Enter JavaScript file URLs for code to be loaded with this plug-in.

      Enter JavaScript file URLs for code to be loaded with this plug-in. Each URL has to be written on a new line. If you provide a minified version of your file you can use the substitution string #MIN# to include .min, or #MIN_DIRECTORY# to include minified/ in your file URL for a regular page view, and an empty string if the page is viewed in debug mode. You also have access to the substitution string #PLUGIN_FILES# to substitute the value of the plug-in's file prefix.

      JavaScript file URLs you enter here will be emitted within the #GENERATED_JAVASCRIPT# substitution string in the page template.

      You do not need to include opening or closing script tags, just the file URL.

   To view examples, see field-level Help.

5. Click Apply Changes.

19.2.8 Adding Events to a Plug-in

Add events to an item, region, or dynamic action type plug-in, to enable them to be exposed to dynamic actions.

For example, suppose you have a Slider plug-in that exposes events such as Start Slide, Sliding, and Stop Slide, and 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 Edit page appears.

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

19.2.9 Deleting a Plug-in

Delete plug-ins on the Edit page.

You can delete a plug-in if it is not in use. If a plug-in 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 Edit page appears.

4. Click Delete.
5. To confirm, click OK.

19.2.10 Viewing the Plug-in Repository

The Plug-in Repository provides a central location where developers can share and download plug-ins.

The Plug-in 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 APEX Plug-in Repository displays.

19.2.11 Exporting a Plug-in from the Plug-in Page

Export a plug-in definition to a file.

Plug-in export files can be imported into any Oracle APEX application. You can access the Export page from the Shared Components, Plug-ins page, as described here, or from the Export 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. Choose Application - Select an application
   2. Plug-in - Select the plug-in to export.
   3. Click Export.
5. Click Export.

   A downloads complete message appears.

See Also:

• Importing a Plug-in from the Plug-in Page

• Exporting Plug-ins

19.2.12 Importing a Plug-in from the Plug-in Page

Import a plug-in definition to a file.

Import a plug-in from the Shared Components, Plug-ins page, as described here, or from the Import home page.

To import 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. Click Import.

   The import Plug-in page appears.

4. On Import:
   1. Drag and drop, or navigate to the file.
   2. File Type - Select Plug-in.
   3. File Character Set - Verify that File Character Set is correct.
   4. Click Next.

      Once you import a file, you have the option to install it. You can also install this file at a later time by navigating to the Export Repository.

5. To install an imported file, click Next.
6. On Install Plug-in:
   1. Install Into Application - Select the target application. You can install the plug-in into the same application or into a different application.

      Tip:

      When you install a plug-in into the current application, the new plug-in will overwrite an existing plug-in having the same plug-in name. If the installation succeeds, the installation of the plug-in becomes permanent. If any errors are encountered, the actions are rolled back, resulting in no permanent changes.
   2. Click Install Plug-in.

See Also:

Importing Plug-ins

19.2.13 Resetting the Plug-in Interactive Report

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.14 Viewing Plug-in Utilization Page

The Plug-in Utilization page displays which pages, components, and regions use each plug-in.

To view the Plug-in Utilization 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. Click Utilization.

   The Plug-in Utilization page appears.

19.2.15 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 the Plug-in History 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. Click History.

   The Plug-in History page appears.