C H A P T E R  2

Plug-In Fundamentals

Plug ins are shared component objects. Like other shared components, they are local to an application and can be made accessible (via subscriptions) to other applications in the same workspace.

The main part of a plug in consists of PL/SQL code with JavaScript and CSS as complimentary code (when applicable). A plug in consists of one or more PL/SQL functions. These functions can either reside in the database (in a package or a set of functions) or be included within the plug in. There are specific headers for each type of function (i.e., they must take in a certain set of parameters and return a specific type). What happens in each function is entirely up to you, the plug in developer.

Certain types of plug ins can also leverage third-party web files, such as JavaScript and CSS files. These files can be stored in APEX or on a web server, or bundled as part of the plug in. The PL/SQL code in the plug in must explicitly load these third-party files.

Plug ins also contain attributes that, like native APEX objects, allow developers to customize the use of the object. Attributes are either global or local. The PL/SQL functions have access to these attributes.

Creating a Plug-In

Before looking at all the plug-in options, you will need to create an “empty” or “skeleton” plug in. An empty plug-in is just a plug-in with no code in it yet. Later chapters will discuss how to build each plug-in type in detail and will reference this section for the initial steps to create a plug-in. The following steps describe how to create an empty plug-in:

1. In the Application Builder, create an empty application with a blank page, Page 1.
2. Select the new application, and then go to the SharedComponents section. Under the User Interface region, click the “Plug-ins” link, as shown in Figure 2-1.
   

   Figure 2-1. Shared Components “Plug-ins” link

3. The Plug-ins page displays all the current plug-ins associated with your application, as shown in Figure 2-2. Click the Create button to create a new plug-in.
   

   Figure 2-2. List of plug-ins

4. Enter Test for the Name and Internal Name fields. Select “item” as the type, and click the Create button to complete creating an empty plug-in, as shown in Figure 2-3. All of the options will be discussed in the next part of this chapter.
   

   Figure 2-3. Creating a plug-in

Plug-In Components

It is important to have a good understanding of each of the options before building your first plug-in. This section will cover all the available options or components involved in building a plug-in. If some components seem a bit confusing, don't worry. They will all be used throughout the demos in this book. To help follow along, edit the Test “empty” plug-in that you created in the previous section.

Name

Like most APEX objects, the Name section allows you to define the name and type for the plug-in, as shown in Figure 2-3. The following fields are required in the Name section:

Name: This is the name that other developers will see when they use a plug-in object. If developing plug-ins for the community, you may want to prefix the name with your company name.

Internal Name: This is a unique internal name that is not visible to APEX developers. APEX uses the internal name to register your plug-in in an application. It's recommended that you use the reverse DNS name of your corporate website along with the plug-in name to help maintain uniqueness—for example, COM.CLARIFIT.FROMTODATEPICKER. APEX uses the internal name to determine if a plug-in is being installed or updated, so it's important not to change it once it's been released. Once the plug-in has been used in an application, the internal name cannot be changed.

Type: The type of plug-in that you're building; there are six different types of plug-ins: authentication, authorization, dynamic action, item, region, and process. Plug ins can be run as part of the render, validation, or page process. Table 2-1shows how each type of plug in can be used in an APEX page. Once a plug-in has been used in an application, the type cannot be changed. The type cannot be changed because each plug-in type has a distinct set of attributes that will become evident in the Callbacks section.

The plug-in type determines when, and how, the plug-in will be used, as shown in Table 2-1. Plug-ins that can be rendered usually (except for authorization types) require HTML code to be sent to the browser. Validation executions happen once the page is submitted. Processes can happen while the page is being rendered or when the page is submitted.

Category: Dynamic actions are broken up into various categories, shown in Figure 2-4, to help developers quickly find the appropriate dynamic action to use. The category that a dynamic action belongs to has no impact on the application. The Category option, shown in Figure 2-5, appears only when the Type field is set to Dynamic Action.

Figure 2-4. Dynamic action categories

Figure 2-5. Plug-in category options

Subscription

You can share certain types of Shared Components objects in APEX with other applications within the same workspace. This sharing mechanism is called subscriptions. Subscriptions also allow you to subscribe to these objects. This means that you change something in your main object (referred to as a master object) in an application and push your changes to other applications that subscribe to the object. If you are unfamiliar with subscriptions, please refer to the manual.

The Subscription section, as shown in Figure 2-6, behaves exactly like other objects in APEX that support the same functionality. APEX allows you to create a master object. When the master object changes, you can push the changes to other objects that subscribe to it.

Figure 2-6. Plug-in Subscription section

Subscriptions may be useful if you have a plug-in that is used across multiple applications. If you need to update it, you can update the master copy and have APEX push the changes to all the other applications that subscribe to it. For more information about how to use subscriptions, refer to the APEX documentation.

Settings

The Settings section contains one option that is present for all plug ins. This option is the File Prefix option.

File Prefix: The File Prefix, as shown in Figure 2-7, defines the root directory to reference third-party files such as JavaScript and CSS. #PLUGIN_PREFIX# should be used if the files are included as part of the plug in. You can also reference other APEX substitution strings, such as #IMAGE_PREFIX# and #APP_IMAGES#, as well as a webserver URL. If referencing a web server, you should include the trailing forward slash (/) to avoid having to include it in all references to files—for example: http://www.clarifit.com/files/ instead of http://www.clarifit.com/files.

Figure 2-7. Plug-in Settings section

Most plug ins will also contain custom attributes. Application-level attributes will also appear in the Settings section. For example, as part of the item plug in demo, you will create a special date picker. Figure 2-8shows the custom application attribute Icon Location that is used as part of the plug in. Icon Location is an application-level attribute that is applicable to all instances of the From To Date Picker in the application.

Figure 2-8. Plug-in setting with custom attribute

Source

The main part of a plug in is contained in PL/SQL code. The Source section contains the following options, as shown in Figure 2-9.

PL/SQL Code: The plug in architecture allows you to either include the PL/SQL code as part of the plug in or reference packages and functions in the database. If bundling the PL/SQL code as part of the plug in, you'll need to include it in the PL/SQL Code text area. The PL/SQL code is called from the callback functions, which are covered in the next section.

Do Not Validate PL/SQL Code: Like other PL/SQL and SQL regions, APEX gives you the option to exclude code from being validated when building your application. If this checkbox is selected, and code is put in the PL/SQL Code text area, it will be validated only at runtime. Unless there is a very specific requirement, it is recommended to leave this checkbox unchecked.

Figure 2-9. Plug-in Source section

1Callbacks

Callback functions are the main drivers for plug ins. Callback functions are PL/SQL functions that render items and regions, setup dynamic actions, execute authorizations and processes, validate items, and handle AJAX calls. Each of the plug ins has a different set of callback functions. Table 2-2showsall of the required and optional callback functions for each plug in type.

Each of the callback functions passes in several parameters and returns an APEX_PLUGIN type. Click the help link to obtain the required function headers for each of the callback functions. Detailed information about each of APEX_PLUGIN types can be found in the APEX API documentation.

In the Callback section, you need to enter only the function name that APEX will call. The functions can reference either a package or function in the database, or a function that was provided in the PL/SQL Code region. The following is a list of all the callback functions and summary of what they do:

Render: The render callback function is used to render the element, load JavaScript and CSS files, and execute JavaScript code.

AJAX: If the plug in requires an AJAX call, this function will handle it. Like standard AJAX calls, you can reference the apex_application.g_x01 ~ g_x10 variables that are passed from the client back to the server as part of the AJAX request.

Validation: Starting in APEX 4, certain types of items have default validations. For example, on most items, you can select if a value is required, as shown in Figure 2-10, and enable these validations to be fired when submitting the page. It's important to note that the validation function will be run only if the APEX developer decides to as part of the submit process.

Figure 2-10. Page item Settings section

Execution: The execution callback function is the only callback function available for process and authorization type plug ins.

Session sentry: The session sentry function is used to validate that the current session is valid. If left blank, APEX will default to its session validation function.

Invalid session: Function to call if session is deemed invalid

Authentication: This function will be run during the login process to ensure that the user's credentials are valid.

Post logout: Once APEX ends the user's session, this function will be called. It will determine where the user should go.

Callback functions can be a bit confusing when encountering them for the first time. The demos in the following chapters will use each of the function types just listed to help you get comfortable using them in your own plug ins.

Standard Attributes

The Standard Attributes section contains a set of attributes that are related to the plug in type. The following example demonstrates how modifying a standard attribute will affect the available options for an APEX object:

1. In the Test plug-in that you created in the previous section, scroll down to the Standard Attributes section, as shown in Figure 2-11, and ensure that all options are unchecked.
   

   Figure 2-11. Item plug-in Standard Attributes section

2. Create a new item on a page (in this example, Page 1). Select the item type as Plug-ins, as shown in Figure 2-12.
   

   Figure 2-12. Create Item section

3. Select the Test plug-in, as shown in Figure 2-13, and click the Next button. You created the Test plug-in in the previous section.
   

   Figure 2-13. Selecting plug-in

4. Enter the same values in Figure 2-14, and click the Next button.
   

   Figure 2-14. Creating item name

5. Leave the Source page with the default values, and click the Create Item button to finish.
6. Edit P1_X. On the Edit Page Item page, there's a minimal set of options available for the item, as shown in Figure 2-15. Note that the Security, Configuration, and Comments sections were omitted from this figure.
   

   Figure 2-15. Item with no standard attributes

7. Go back and edit the Test plug in. Check the Is Visible Widget box, as shown in Figure 2-16, and click the Apply Changes button to save it.
   

   Figure 2-16. Standard Attributes option checked

8. Go back to Page 1 and edit P1_X. You'll notice that it now has more available options and some new regions. Figure 2-17 shows the new options available for P1_X. Note that the Security, Configuration, Help Text, and Comments sections were omitted from this figure.
   

   Figure 2-17. Item with Is Visible standard attribute enabled

If a standard attribute option is changed while a plug in is already in use, the option is still part of the APEX object but not available for a developer to modify. For example, in the previous example, you enabled the Is Visible Widget option. Enabling this attribute allows you to enter a label for the P1_X item. If you entered a label for P1_X, and then disabled the Is Visible Widget option in the plug in, the label would disappear from the P1_X item edit page. The label would still exist in the underlying table that stores P1_X information. It is important to remember this when modifying standard attributes once a plug in has been used within an application.

Custom Attributes

Custom attributes allow you to configure options that can be referenced in your plug-in callback code. Custom attributes are already present in standard APEX objects. For example, if you create a password page item (see Figure 2-18), its attributes are “Submit when Enter pressed” and “Does not save state”.

Figure 2-18. Password item custom attributes

There are two types of custom attributes. The following list describes them along with their differences.

Application: Application attributes are attributes that are global for the plug in across the entire application. They can be configured only in the edit plug in page. For example, if you created a plug in that uses a color attribute that should be consistent across the application, you would create an application attribute to store the color.

Component: Component attributes are attributes that are specific for an instance of the plug in. The password example that was previously discussed is a good example of component attributes.

You can choose to have APEX automatically replace substitution strings if they are used in the custom attribute value by setting the Substitute Attribute Values to Yes. For example, if a developer entered in &APP_ID. as a value and Substitute Attribute Values was set to Yes, then the value would be 100 (assuming the application ID was 100). If you set Substitute Attribute Values to No, then you must manually do string substitutions using apex_plugin_util.replace_substitutions.

To create either an application or component attribute, click the Add Attribute button, as shown in Figure 2-19. Attributes are stored as type VARCHAR2 in the database, so you will need to do explicit conversions if required. There's a limit of 15 attributes for each application and component attribute. The following subsections describe the available options for attributes.

Figure 2-19. Custom Attributes section

Name

The Name section allows you to define how the attributes appear on the object edit page. The following list describes the available options shown in Figure 2-20.

Scope: The scope determines the type of plug in attribute. The two types of attributes were mentioned earlier. Once an attribute has been saved, the scope cannot be modified.

Attribute: The attribute number determines the column in the table that this attribute is stored in. There's currently room for 15 attributes for each type. Since this is used to store the attribute value in a table, the attribute number cannot be modified once an attribute has been saved.

Display Sequence: Like other APEX objects, you can control the display order of each attribute.

Label: The label is the name displayed to the APEX developer using the plug in.

Figure 2-20. Custom attribute: Name

Settings

The Settings section, as shown in Figure 2-21, determines the attribute type. The options vary depending on the selected type. The available options are as follows:

Type: The type of attribute will determine the rest of the available options in the Settings section. Implicit validations will occur based on the type. For example, if the type is set to Integer and a developer enters abc, an error message will be displayed. If you click the help link (i.e., the Type label), you will get a list of all the available types along with some additional information. Once a type has been saved and the plug-in has been used in the application, it cannot be modified.

Figure 2-21. Custom attribute: Settings

List of Values

The List of Values section, as shown in Figure 2-22, will appear only if the type is set to Checkboxes or Select List. It allows you to define a static list of values for a developer to select a value from.

Figure 2-22. Custom attribute: List of Values

Default Value

If entered, the default value will appear as the value for the attribute when the plug in is first created. If the type is set to Checkboxes or Select List and it is a required attribute, then a default value is required.

Condition

The Condition section is different than standard Condition sections for APEX objects. It determines the dependency for the current attribute with respect to other attributes for the plug in. For example, suppose you had a plug in that drew shapes and had the following attributes:

• Shape(square, circle)
• Length
• Width
• Radius

You would not want the Radius attribute to be displayed when the shape is a square. Instead you would conditionally display the Length, Width, and Radius attributes depending on the type of shape. Figure 2-23 shows the Condition section for the Radius attribute.

Figure 2-23. Custom attribute: Condition

Depending on: This is the element that the current attribute is dependent on. In the example, it was Shape.

Condition Type: The condition determines how to evaluate against the “Depending on” value.

Expression: The value to compare against. If “in list” or “not in list” is selected, the expression must be a comma-separated list. The expression value is case-sensitive.

Help Text (for the Custom Attribute)

The Help Text section for a custom attribute allows you to provide some additional information for developers that are leveraging the plug in. This text will never be displayed to end users, just developers. Like all other APEX help text, developers need to click the attribute label to see the help text. HTML code is allowed in the help text.

Files

The Files section allows you to include third-party files with your plug in, as shown in Figure 2-24. If files are stored in the Files section, #PLUGIN_PREFIX# should be used as the File Prefix, as shown in Figure 2-7.

Figure 2-24. Plug-in Files section

The advantage of storing the files as part of the plug in is that you don't need to worry about connections to other web servers, etc. If your application receives a lot of page views or you need to improve the page load time, it may help to store the file on a web server. When developing plug ins, it helps to store the files on a web server that allows you to easily manipulate the files.

When using files, you should include a version number at the end of the file name. Including a unique version number for each file will make sure the browser uses the most recent version of the file rather than an older, cached copy. This concept is discussed in detail in Chapter 7.

Events

Events are custom JavaScript events that will be triggered by the plug in. Some built-in JavaScript events that you may already know are onClick and onChange. Figure 2-25 shows the Events section on the plug-in page.

Figure 2-25. Plug-in Events section

Since events are tightly coupled with JavaScript code, they are available only for plug ins that relate to page rendering: item, region, and dynamic action. Registering an event with a plug in requires two components on the plug in form:

Name: Name is the display name that is shown to other APEX developers when they are creating a dynamic action.

Internal Name: This is the name that is used in the JavaScript code to trigger the event. APEX will lowercase the internal name automatically so you cannot use camel case in your JavaScript code that manages this event.

Events can be referenced by dynamic actions or by custom JavaScript code. If used by a dynamic action, they will show up in the list of dynamic actions. The following example demonstrates the relationship with dynamic actions:

1. Edit the skeleton plug-in that you previously created at the beginning of this chapter. Scroll down to the Events region, as shown in Figure 2-25. Click the Add Event button.
2. The page will reload. Scroll back down to the Events region, which now has a blank row for a new event, and enter Dummy Event for the Name and dummy event for the Internal Name, as shown in Figure 2-26. Click the Apply Changes button to save the modifications.
   

   Figure 2-26. Plug-in Events section

3. On Page 1, create a new dynamic action by right-clicking the Dynamic Action tree element, and select Create from the context menu, as shown in Figure 2-27.
   

   Figure 2-27. Creating a dynamic action

4. Select Advanced and click the Next button.
5. In the Name field, enter Test and click the Next button to continue.
6. On the When page, expand the list of events. You'll notice a list of built-in events that are part of APEX. If you scroll to the bottom of the list, as shown in Figure 2-28, you'll notice Dummy Event in the list of events.
   

   Figure 2-28. Dummy Event in dynamic action event list

7. Since you don't need this dynamic action, hit the Cancel button to exit from the Dynamic Action wizard.

Events can be a bit confusing the first time when learning about them. Some of the demos will leverage events to help you understand how to build the additional functionality within your plug in JavaScript code.

Information

The Information section, as shown in Figure 2-29, allows you to include some metadata about your plug in. It contains the following fields:

Version: Like APEX applications, plug ins contain version numbers. It is useful to maintain the version number to indicate if a new version of the plug in is available.

About URL: You can put a link to a page that contains more information about the plug in. When a plug in is built for public consumption, developers tend to put their organization's web site on it. If it is built for internal use, you can put a link to a wiki page, which may contain more information about the business requirements for the plug in, etc.

Figure 2-29. Plug-in Information section

Help Text (for the Plug-In)

It is recommended that you include any instructions in the Help Text section for the plug-in as a whole, as shown in Figure 2-30. The Help Text section can include both plain text and HTML markup. You can also include additional information, such as license information and documentation, in the Help Text section as well.

Figure 2-30. Plug-in Help Text section

Licensing

You can create plug-ins to give away, possibly in support of marketing your services. You can also create plug-ins to sell. The plug-in Help Text section mentioned in the preceding section is an excellent place to place your license terms, or at least to reference them.

Some plug-in developers prefer to publish their work under various open source licenses. There are many different open source licenses, each written with somewhat different end goals in mind. The following URL is a good source for information on the various open source licenses available:

If you choose to use an open sources license, you can just reference the license name and choose to include only the URL to that license in the help text for your plug-in. Users can follow the link to the actual license text if they are interested in the details.

Summary

This chapter covered all the components that make up a plug in and introduced some of the APIs required to build a plug in. In the following chapters, you will build each different type of plug in, and that will make use of all the components that were covered in this chapter.