This section describes how to add plug-ins to your application, and how to manage reuse and sharing. Plug-in examples are available on the Oracle Application Express Plug-in Repository on the Oracle Technology Network, and are included in the Sample Database Application.
See Also:
"Viewing the Plug-in Repository"Plug-ins enable developers to declaratively extend, share, and reuse the built-in types available with Oracle Application Express.
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 in to 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.
For Plug-in implementation examples, go to the Oracle Learning Library at the following location, click the link at the bottom of the page to access the library, then enter search criteria for Oracle Application Express (APEX) Product OBEs:
http://www.oracle.com/technetwork/tutorials/index.html
To access the plug-ins:
Navigate to the Plug-ins page.
Navigate to the Workspace home page.
Click the Application Builder icon.
Select an application.
Click Shared Components.
Under User Interface, select 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. Available controls include:
Search icon - Resembles a magnifying glass. Click this icon to narrow your search to only specific columns. To search all columns, select All Columns.
Text area - Enter case insensitive search criteria (wildcard characters are implied) and then click Go.
Go button - Executes a search or applies a filter.
View icons. Use this control to toggle between icon and report views. To change the view, select one of the following:
View Icons (default) displays each plug-in as a large icon.
View Report displays each plug-in as a line in a report.
Actions menu - Displays the Actions menu. Use this menu to customize the report view. See "About the Actions Menu".
To edit a plug-in:
Navigate to the Plug-ins page. See "Accessing 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 item Help, "Creating a Plug-in", "Adding Custom Attributes to a Plug-in", "Uploading Files to Associate with a Plug-in" and "Adding Events to a Plug-in"
Click Apply Changes.
Tip:
During the following steps, see item help to learn more about a specific field.To create a plug-in:
Navigate to the Plug-ins page. See "Accessing Plug-ins".
Click Create.
The Plug-in Create/Edit page appears.
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.
Tip:
To insure the internal name is a globally unique name worldwide, it is recommended that your organization domain name be used as a prefix to internal plug-in names. For example, a domain name ofmycompany.com prefixed to a plug-in named Slider, would result in an internal name of COM.MYCOMPANY.SLIDER.Type (Required) - Select the type of component that can use this plug-in. Settings under Callbacks and Standard Attributes will differ depending on the plug-in type selected. Refer to following sections for details.
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 pop up list. Otherwise, leave the field blank to make this the master copy of this plug-in.
For Settings:
File Prefix - Use the default, #PLUGIN_PREFIX#, to reference files that are stored with your plug-in definition in the database. This prefix determines the virtual path the Web server uses to point to the files of the plug-in. For improved performance, you can also store your plug-in files on your Web server and use #IMAGE_PREFIX# or any valid URL to reference them.
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.
Do not validate PL/SQL code (parse PL/SQL code at runtime only) - Check this option to parse the PL/SQL code at runtime only. Otherwise, the code will be parsed when the plug-in is created.
Under Callbacks:
Render Function Name (only available for Region, Item, and Dynamic Action type plug-ins) - Enter the name of the PL/SQL function called to render the plug-in.
AJAX Function Name (only available for Authentication, Region, Item and Dynamic Action type plug-ins) - Enter the name of the PL/SQL function used by the plug-in to load additional data with an AJAX call.
Validation Function Name (only available for Item type plug-ins) - Enter the name of the PL/SQL function the plug-in can use to perform basic validations on the submitted data.
Execution Function Name (only available for Authorization and Process type plug-ins) - Enter the name of the PL/SQL function called to execute the plug-in.
Session Sentry Function Name (only available for Authentication type plug-ins) - Enter the name of the PL/SQL function the plug-in uses to perform the session sentry verification.
Invalid Session Function Name (only available for Authentication type plug-ins) - Enter the name of the PL/SQL function the plug-in calls if an invalid session is detected. For example, use this function to call a Single Sign-On sever.
Authentication Function Name (only available for Authentication type plug-ins) - Enter the name of the PL/SQL function the plug-in uses to perform the verification of the entered user credentials.
Post Logout Function Name (only available for Authentication type plug-ins) - Enter the name of the PL/SQL function the plug-in calls after Application Express has terminated the current session. Use this function to logout from other systems like a Single Sign-On sever.
Note:
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. See item help for further details and examples.Under Standard Attributes (not available for Authorization Scheme and Process type plug-ins):
For Authentication Scheme type plug-ins, specify the following attribute:
Has Session not valid Attribute - If selected, the Stop Execution on Error field is available for the action.
For Dynamic Action type plug-ins, identify the attributes that apply to this plug-in:
For Item(s) - The dynamic action supports selection of items as the affected elements.
For Region - The dynamic action supports selection of a region as the affected elements.
For DOM Object - The dynamic action supports selection of DOM Objects as the affected elements.
For jQuery Selector - The dynamic action supports specifying a jQuery selector as the affected elements.
For Triggering Element - The dynamic action supports selection of the triggering element as the affected elements.
For Event Source - The dynamic action supports selection of your event source as the affected elements.
Affected Element Required - The dynamic action requires an affected element to be specified.
Check "Fire on page load" - Defines the default value for the action's Fire on Page Load field.
Has Stop Execution on Error Attribute - The Stop Execution on Error field is available for the action.
For Item type plug-ins, identify the attributes that apply to this plug-in:
Is Visible Widget - The widget is visible.
Session State Changeable - The value for an item can be changed in session state. The Is Visible Widget attribute must be checked.
Has Read Only Attribute - The user can specify a "Read Only" condition for the item. The Is Visible Widget attribute must be checked for this attribute to be enabled.
Has Escape Special Characters Attribute - The item has the Escape special characters field in the Security section when the item is edited. The Is Visible Widget attribute must be checked.
Has Quick Pick Attributes - The item has quick pick attributes. The Is Visible Widget attribute must be checked.
Has Source Attributes - The item has source related attributes such as Source Used, Source Type and Format Mask.
Format Mask Date Only - For items that handle date information, the Format Mask field popup restricts the date selections by displaying date values to select from. The Has Source Attributes must be checked.
Format Mask Number Only - For items that handle numeric information, the Format Mask field popup restricts the numeric selections by displaying numeric values to select from.
Has Element Attributes - The item has element attributes such as Horizontal/Vertical Alignment, HTML Form Element Attributes, and Pre/Post Element Text.
Has Width Attributes - The item width can be controlled.
Has Height Attribute - The item height can be controlled.
Has Element Option Attribute - The item allows specification of additional option attributes when rendering multi-selection elements such as radio groups of check boxes.
Has Encrypt Session State Attribute - When editing the item, the Store value encrypted in session state displays under the Security region.
Has List of Values - The item has an associated list of values. The Is Visible Widget attribute must be checked.
List of Values Required - For items that handle lists of values, a list of values must be defined. The Has List of Values attribute must be checked.
Has LOV Display Null Attributes - The item is associated with a list of values that is allowed to include null values. The Has List of Values attribute must be checked.
Has Cascading LOV Attributes - The item has cascading LOV related attributes. The Has List of Values attribute must be checked.
For Region type plug-ins, check the following to enable options as described here:
Region Source is SQL Statement - The region source is a SQL Statement. When checked, a minimum and a maximum number of columns the query can return can be specified and SQL Examples display to help the user.
Region Source is Plain Text - The region source is plain text.
Region Source Required - If region source is a SQL Statement, this attribute makes this a required value.
Has "Page Items to Submit" Attribute - If region source is a SQL Statement, this attribute allows you to specify those page items which should be set in session state when executing an AJAX call for that region.
Has "Escape Special Characters" Attribute - The region has the Escape special characters field in the Security section when the region is edited.
For 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 will never be displayed when the application is running.
To learn more about each option, see item Help.
Click Create.
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 "Adding Custom Attributes to a Plug-in", "Uploading Files to Associate with a Plug-in", and "Adding Events to a Plug-in".
A plug-in attribute is used to prompt the developer for additional data in the Application Builder when the plug-in is used.
Tip:
During the following steps, see item help to learn more about a specific field.To add custom attributes to the plug-in:
Navigate to the Plug-ins page. See Accessing Plug-ins.
Click the plug-in you want to modify.
The Plug-in Create/Edit page appears.
Under Custom Attributes, enable or disable 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.
Scroll down to Custom Attributes and click Add Attribute.
The Edit Attribute page appears.
Under name:
Scope - Select Application if the attribute is only defined once for the application. Select Component if the attribute is defined each time the plug-in is referenced in a component.
Attribute - Enter the sequence that correlates with the ATTRBUTE_XX columns and to the PL/SQL types defined in the APEX_PLUGIN package.
Display Sequence - Enter the display sequence for this plug-in attribute in the Application Builder.
Label - Enter the label that displays for this attribute in the Application Builder.
For Settings:
Type - Select the attribute type.
Required - Select Yes if this attribute must be specified. Otherwise, select No.
Translatable - Select Yes if this attribute is included in the translation file, otherwise, select No.
Display Width - Enter the length in characters displayed for this attribute in the Application Builder.
Maximum Width - Enter the maximum number of characters users are allowed to enter for this attribute in the Application Builder.
Under Default Value, specify a value to be used for this plug-in attribute when a new component is created that uses this plug-in. Use Y and N for attributes of type Yes/No.
Under Condition:
Depending on - Select the attribute on which the current attribute depends.
Condition Type (only displays if dependant attribute) - Select the type of condition that must be met in order for this attribute to render.
Expression (only displays if needed for condition type)- Enter expression that must meet the selected condition type. See item help for details.
For Help Text, specify the help text that is displayed as context sensitive help for the attribute in the Application Builder.
Under Comments, enter comments or notes that are never displayed when the application is running.
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.Upload image, CSS, and JavaScript files you want to associate with your plug-in. Use #PLUGIN_PREFIX# in uploaded CSS and JavaScript files to reference another uploaded file. See the Plug-in Files region on the right of the Upload New File page for more details.
For example, in a CSS file the reference might be:
.sidebar{
background-image:url(#PLUGIN_PREFIX#flowers.png);
}
To upload a file:
Navigate to the Plug-ins page. See "Accessing Plug-ins".
Click the plug-in you want to upload to.
The Plug-in Create/Edit page appears.
Scroll down to Files and click Upload New File.
The Upload New File page appears.
For 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.
Adding 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 Plug-ins page. See "Accessing Plug-ins".
Click the plug-in you want to edit.
The Plug-in Create/Edit page appears.
Scroll down to Events and click Add Event.
A new row displays under Events.
Under Events, specify the following:
Name - The display name under which the plug-in event shows up 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 Apply Changes.
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 Plug-ins page. See "Accessing Plug-ins".
Click the plug-in you want to delete.
The Plug-in Create/Edit page appears.
Click Delete.
Click OK to confirm.
The purpose of the Plug-in Repository is to provide 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 Plug-ins page. See "Accessing Plug-ins".
Click View Plug-in Repository.
The Oracle Application Express Plug-in Repository displays.
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 Application Builder Home page. See "Importing Plug-ins".
To import a plug-in:
Navigate to the Plug-ins page. See "Accessing Plug-ins".
Click Import.
The import Plug-in page appears.
For Specify File:
Import file - Select 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.
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. See "Exporting Plug-ins".
Navigate to the Plug-ins page. See "Accessing Plug-ins".
Under Tasks, click Export Plug-in.
The Export Plug-in page appears.
For Application, select the application to export the plug-in from.
Click Set Application.
For Export Plug-in:
Plug-in - Select plug-in.
File Format - Select file format of export plug-in.
Click Export Plug-in.
Select Save File, and click OK.
Downloads complete message appears.
To reset the interactive report:
Navigate to the Plug-ins page. See "Accessing Plug-ins".
Click Reset.
See Also:
The Plug-in Utilization page displays which pages, components, and regions use each plug-in.
To view plug-in utilization:
Navigate to the Plug-ins page. See "Accessing Plug-ins".
Click Utilization.
The Utilization page appears.
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 Plug-ins page. See "Accessing Plug-ins".
Click History.
The History page appears.