Oracle APEX Plug-ins

Oracle APEX 4.0 Cookbook

Over 80 great recipes to develop and deploy fast, secure, and modern web applications with Oracle Application Express 4.0

• Create feature-rich web applications in APEX 4.0
• Integrate third-party applications like Google Maps into APEX by using web services
• Enhance APEX applications by using stylesheets, Plug-ins, Dynamic Actions, AJAX, JavaScript, BI Publisher, and jQuery
• Hands-on examples to make the most out of the possibilities that APEX has to offer
• Part of Packt’s Cookbook series: Each recipe is a carefully organized sequence of instructions to complete the task as efficiently as possible

  Introduction

In APEX 4.0, Oracle introduced the plug-in. A plug-in is an extension to the existing functionality of APEX. The idea behind plug-ins is to make life easier for developers. Plug-ins are reusable and can be exported and imported. In this way, it is possible to create functionality which is available to all APEX developers. It is also possible to install and use them without having knowledge of what is inside the plug-in.

APEX is actually a program that converts your settings from the APEX builder to HTML and JavaScript. For example, if you created a text item in the APEX builder, APEX converts this to the following code (simplified):

<input type=”text” id=”P12_NAME” name=”P12_NAME” value=”your name”>

When you create an item type plug-in, you actually take over this conversion task of APEX and you generate the HTML and JavaScript code yourself by using PL/SQL procedures. That offers a lot of flexibility because now you can make this code generic so that it can be used for more items.

The same goes for region type plug-ins. A region is a container for forms, reports, and such. The region can be a div or a HTML table. By creating a region type plug-in, you create a region yourself with the possibility to add more functionality to the region.

There are four types of plug-in:

• Item type plug-ins
• Region type plug-ins
• Dynamic action plug-ins
• Process type plug-ins

In this article, we will discuss all four types of plug-in.

Creating an item type plug-in

In an item type plug-in you create an item with the possibility of extending its functionality. To demonstrate this, we will make a text field with a tooltip. This functionality is already available in APEX 4.0 by adding the following code to the HTML form element attributes text field in the Element section of the text field:

onmouseover=”toolTip_enable(event,this,’A tooltip’)”

But you have to do this for every item that should contain a tooltip. This can be made more easy by creating an item type plug-in with a built-in tooltip. And if you create an item of type plug-in, you will be asked to enter some text for the tooltip.

Getting ready

For this recipe, you can use an existing page with a region where you can put some text items on.

How to do it…

1. Go to Shared Components | User Interface | Plug-ins.

   

2. Click on the Create button.
3. In the name section, enter a name in the name text field. In this case, we enter tooltip.
4. In the internal name text field, enter an internal name. It is advised to use your company’s domain address reversed to ensure the name is unique when you decide to share this plug-in. So, for example, you can use com.packtpub.apex.tooltip.
5. In the source section, enter the following code to the PL/SQL code textarea:

   function render_simple_tooltip (
   p_item in apex_plugin.t_page_item
   , p_plugin in apex_plugin.t_plugin
   , p_value in varchar2
   , p_is_readonly in boolean
   , p_is_printer_friendly in boolean )
   return apex_plugin.t_page_item_render_result
   is
   l_result apex_plugin.t_page_item_render_result;
   begin
   if apex_application.g_debug
   then
   apex_plugin_util.debug_page_item (
   p_plugin => p_plugin
   , p_page_item => p_item
   , p_value => p_value
   , p_is_readonly => p_is_readonly
   , p_is_printer_friendly => p_is_printer_friendly);
   end if;
   —
   sys.htp.p(‘<input type=”text” id=”‘||p_item.name||'” name=”‘||p_item.name||'” class=”text_field” onmouseover=”toolTip_enable(event,this,’||””||p_item.attribute_01||””||’)”>’);
   —
   return l_result;
   end render_simple_tooltip;

   This function uses the sys.htp.p function to put a text item on the screen. On the text item, the onmouseover event calls the function tooltip_enable(). This function is an APEX function and can be used to put a tooltip on an item. The arguments of the function are mandatory.
   The function starts with the option to show debug information. This can be very useful when you have created a plug-in and it doesn’t work. After the debug information the htp.p function puts the text item on the screen, including the call to tooltip_enable. You can also see that the call to tooltip_enable uses p_item.attribute_01. This is a parameter that you can use to pass a value to the plug-in. That is the following step in this recipe.

6. The function ends with the return of l_result. This variable is of type apex_plugin.t_page_item_render_result. For the other types of plug-in there are also dedicated return types, for example, t_region_render_result.
7. Click on the Create button.
8. The next step is to define the parameter (attribute) for this plug-in. In the Custom Attributes section, click the Add Attribute button.

   

9. In the name section, enter a name in the label text field, for example tooltip.
10. Ensure that the attribute text field contains the value 1.
11. In the settings section, set the type to text.
12. Click on the Create button.
13. In the callbacks section, enter render_simple_tooltip into the render function name text field.
14. Click on the Apply changes button.
15. The plug-in is ready now. The next step is to create an item of type tooltip plug-in.
16. Go to a page with a region where you want to use an item with a tooltip.
17. In the items section, click on the add icon to create a new item.

    

18. Select Plug-ins.

    

19. Now you will get a list of available plug-ins. Select the one we just created, tooltip. Click on Next.
20. In the item name text field, enter a name for the item, for example tt_item.
21. In the region select list, select the region you want to put the item in. Click Next.
22. In the next step, you will get a new option. It’s the attribute you created with the plug-in. Enter the tooltip text here. Click Next.
23. In the last step, leave everything as it is and click the Create item button.
24. You are ready now. Run the page. When you move your mouse pointer over the new item, you will see the tooltip.