(For more resources related to this topic, see here.)
In APEX 4.0, Oracle introduced the plug-in feature. 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 a functionality which is available to all APEX developers. And installing and using them without the need of having a knowledge of what’s inside the plug-in.
APEX translates 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 so on. The region can be a div or an HTML table. By creating a region type plug-in, you create a region yourself with the possibility to add more functionality to the region.
Plug-ins are very useful because they are reusable in every application. To make a plug-in available, go to Shared Components | Plug-ins , and click on the Export Plug-in link on the right-hand side of the page. Select the desired plug-in and file format and click on the Export Plug-in button. The plug-in can then be imported into another application.
Following are the six types of plug-in:
- Item type plug-ins
- Region type plug-ins
- Dynamic action plug-ins
- Process type plug-ins
- Authorization scheme type plug-ins
- Authentication scheme type plug-ins
In this Aricle we will discuss the first five types of plug-ins.
Creating an item type plug-in
In an item type plug-in you create an item with the possibility to extend 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 easily 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 in which you can put some text items.
How to do it…
Follow these steps:
- Go to Shared Components | User Interface | Plug-ins .
- Click on the Create button.
- In the Name section, enter a name in the Name text field. In this case we enter tooltip.
- In the Internal Name text field, enter an internal name. It is advised to use the 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.
- In the Source section, enter the following code in the PL/SQL Code text area:
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 (<input type=”text”) 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 create 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 steps in this recipe.
The function ends with the return of l_result. This variable is of the type apex_plugin.t_page_item_render_result. For the other types of plug-in there are dedicated return types also, for example t_region_render_result.
- Click on the Create Plug-in button
- The next step is to define the parameter (attribute) for this plug-in. In the Custom Attributes section, click on the Add Attribute button.
- In the Name section, enter a name in the Label text field, for example tooltip.
- Ensure that the Attribute text field contains the value 1 .
- In the Settings section, set the Type field to Text .
- Click on the Create button.
- In the Callbacks section, enter render_simple_tooltip into the Render Function Name text field.
- In the Standard Attributes section, check the Is Visible Widget checkbox.
- Click on the Apply Changes button.
The plug-in is now ready. The next step is to create an item of type tooltip plug-in.
- Go to a page with a region where you want to use an item with a tooltip.
- In the Items section, click on the add icon to create a new item.
- Select Plug-ins .
- Now you will get a list of the available plug-ins. Select the one we just created, that is tooltip . Click on Next .
- In the Item Name text field, enter a name for the item, for example, tt_item.
- In the Region drop-down list, select the region you want to put the item in. Click on Next .
- In the next step you will get a new option. It’s the attribute you created with the plug-in. Enter here the tooltip text, for example, This is tooltip text. Click on Next .
- In the last step, leave everything as it is and click on the Create Item button.
- You are now ready. Run the page. When you move your mouse pointer over the new item, you will see the tooltip.
How it works…
As stated before, this plug-in actually uses the function htp.p to put an item on the screen. Together with the call to the JavaScript function, toolTip_enable on the onmouseover event makes this a text item with a tooltip, replacing the normal text item.
There’s more…
The tooltips shown in this recipe are rather simple. You could make them look better, for example, by using the Beautytips tooltips. Beautytips is an extension to jQuery and can show configurable help balloons. Visit http://plugins.jquery.com to download Beautytips. We downloaded Version 0.9.5-rc1 to use in this recipe.
- Go to Shared Components and click on the Plug-ins link.
- Click on the tooltip plug-in you just created.
- In the Source section, replace the code with the following code:
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;
The function also starts with the debug option to see what happens when something goes wrong.
--Register the JavaScript and CSS library the plug-inuses. apex_javascript.add_library ( p_name => 'jquery.bgiframe.min', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'jquery.bt.min', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'jquery.easing.1.3', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'jquery.hoverintent.minified', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'excanvas', p_directory => p_plugin.file_prefix, p_version => null );
After that you see a number of calls to the function apex_javascript.add_library. These libraries are necessary to enable these nice tooltips. Using apex_javascript.add_library ensures that a JavaScript library is included in the final HTML of a page only once, regardless of how many plug-in items appear on that page.
sys.htp.p('<input type="text" id="'||p_item.name||'"
class="text_field" title="'||p_item.attribute_01||'">');
-- apex_javascript.add_onload_code (p_code =>'$("#'||p_item.name||'").bt({ padding: 20 , width: 100 , spikeLength: 40 , spikeGirth: 40 , cornerRadius: 50 , fill: '||''''||'rgba(200, 50, 50, .8)'||''''||' , strokeWidth: 4 , strokeStyle: '||''''||'#E30'||''''||' , cssStyles: {color: '||''''||'#FFF'||''''||',
fontWeight: '||''''||'bold'||''''||'} });'); -- return l_result; end render_tooltip;
Another difference with the first code is the call to the Beautytips library. In this call you can customize the text balloon with colors and other options. The onmouseover event is not necessary anymore as the call to $().bt in the wwv_flow_javascript.add_onload_code takes over this task. The $().bt function is a jQuery JavaScript function which references the generated HTML of the plug-in item by ID, and converts it dynamically to show a tooltip using the Beautytips plug-in.
You can of course always create extra plug-in item type parameters to support different colors and so on per item.
To add the other libraries, do the following:
- In the Files section, click on the Upload new file button.
- Enter the path and the name of the library. You can use the file button to locate the libraries on your filesystem. Once you have selected the file, click on the Upload button.
The files and their locations can be found in the following table:
Libra ry
Location
jquery.bgiframe.min.js
bt-0.9.5-rc1other_libsbgiframe_2.1.1
jquery.bt.min.js
bt-0.9.5-rc1
jquery.easing.1.3.js
bt-0.9.5-rc1other_libs
jquery.hoverintent.minified.js
bt-0.9.5-rc1other_libs
Excanvas.js
bt-0.9.5-rc1other_libsexcanvas_r3
- If all libraries have been uploaded, the plug-in is ready. The tooltip now looks quite different, as shown in the following screenshot:
In the plug-in settings, you can enable some item-specific settings. For example, if you want to put a label in front of the text item, check the Is Visible Widget checkbox in the Standard Attributes section.
For more information on this tooltip, go to http://plugins.jquery.com/project/bt.
Creating a region type plug-in
As you may know, a region is actually a div. With the region type plug-in you can customize this div. And because it is a plug-in, you can reuse it in other pages. You also have the possibility to make the div look better by using JavaScript libraries. In this recipe we will make a carousel with switching panels. The panels can contain images but they can also contain data from a table. We will make use of another jQuery extension, Step Carousel.
Getting ready
You can download stepcarousel.js from http://www.dynamicdrive.com/dynamicindex4/stepcarousel.htm. However, in order to get this recipe work in APEX, we needed to make a slight modification in it. So, stepcarousel.js, arrowl.gif, and arrow.gif are included in this book.
How to do it…
Follow the given steps, to create the plug-in:
- Go to Shared Components and click on the Plug-ins link.
- Click on the Create button.
- In the Name section, enter a name for the plug-in in the Name field. We will use Carousel.
- In the Internal Name text field, enter a unique internal name. It is advised to use your domain reversed, for example com.packtpub.carousel.
- In the Type listbox, select Region .
- In the Source section, enter the following code in the PL/SQL Code text area:
function render_stepcarousel ( p_region in apex_plugin.t_region, p_plugin in apex_plugin.t_plugin, p_is_printer_friendly in boolean ) return apex_plugin.t_region_render_result is cursor c_crl is select id , panel_title , panel_text , panel_text_date from app_carousel order by id; -- l_code varchar2(32767); begin
The function starts with a number of arguments. These arguments are mandatory, but have a default value. In the declare section there is a cursor with a query on the table APP_CAROUSEL. This table contains several data to appear in the panels in the carousel.
-- add the libraries and stylesheets -- apex_javascript.add_library ( p_name => 'stepcarousel', p_directory => p_plugin.file_prefix, p_version => null ); -- --Output the placeholder for the region which is used by--the Javascript code
The actual code starts with the declaration of stepcarousel.js. There is a function, APEX_JAVASCRIPT.ADD_LIBRARY to load this library. This declaration is necessary, but this file needs also to be uploaded in the next step. You don’t have to use the extension .js here in the code.
-- sys.htp.p('<style type="text/css">'); -- sys.htp.p('.stepcarousel{'); sys.htp.p('position: relative;'); sys.htp.p('border: 10px solid black;'); sys.htp.p('overflow: scroll;'); sys.htp.p('width: '||p_region.attribute_01||'px;'); sys.htp.p('height: '||p_region.attribute_02||'px;'); sys.htp.p('}'); -- sys.htp.p('.stepcarousel .belt{'); sys.htp.p('position: absolute;'); sys.htp.p('left: 0;'); sys.htp.p('top: 0;'); sys.htp.p('}'); sys.htp.p('.stepcarousel .panel{'); sys.htp.p('float: left;'); sys.htp.p('overflow: hidden;'); sys.htp.p('margin: 10px;'); sys.htp.p('width: 250px;'); sys.htp.p('}'); -- sys.htp.p('</style>');
After the loading of the JavaScript library, some style elements are put on the screen. The style elements could have been put in a Cascaded Style Sheet (CSS ), but since we want to be able to adjust the size of the carousel, we use two parameters to set the height and width. And the height and the width are part of the style elements.
-- sys.htp.p('<div id="mygallery" class="stepcarousel"
style="overflow:hidden"><div class="belt">'); -- for r_crl in c_crl loop sys.htp.p('<div class="panel">'); sys.htp.p('<b>'||to_char(r_crl.panel_text_date,'DD-MON-YYYY')||'</b>'); sys.htp.p('<br>'); sys.htp.p('<b>'||r_crl.panel_title||'</b>'); sys.htp.p('<hr>'); sys.htp.p(r_crl.panel_text); sys.htp.p('</div>'); end loop; -- sys.htp.p('</div></div>');The next command in the script is the actual creation of a div. Important here is the name of the div and the class. The Step Carousel searches for these identifiers and replaces the div with the stepcarousel. The next step in the function is the fetching of the rows from the query in the cursor. For every line found, the formatted text is placed between the div tags. This is done so that Step Carousel recognizes that the text should be placed on the panels.
--Add the onload code to show the carousel -- l_code := 'stepcarousel.setup({ galleryid: "mygallery" ,beltclass: "belt" ,panelclass: "panel" ,autostep: {enable:true, moveby:1, pause:3000} ,panelbehavior: {speed:500, wraparound:true,persist:true} ,defaultbuttons: {enable: true, moveby: 1,
leftnav:
["'||p_plugin.file_prefix||'arrowl.gif", -5,
80], rightnav:
["'||p_plugin.file_prefix||'arrowr.gif", -20,
80]} ,statusvars: ["statusA", "statusB", "statusC"] ,contenttype: ["inline"]})'; -- apex_javascript.add_onload_code (p_code => l_code); -- return null; end render_stepcarousel;The function ends with the call to apex_javascript.add_onload_code. Here starts the actual code for the stepcarousel and you can customize the carousel, like the size, rotation speed and so on.
- In the Callbacks section, enter the name of the function in the Return Function Name text field. In this case it is render_stepcarousel.
- Click on the Create Plug-in button.
- In the Files section, upload the stepcarousel.js, arrowl.gif, and arrowr.gif files.
For this purpose, the file stepcarousel.js has a little modification in it. In the last section (setup:function), document.write is used to add some style to the div tag. Unfortunately, this will not work in APEX, as document.write somehow destroys the rest of the output. So, after the call, APEX has nothing left to show, resulting in an empty page. Document.write needs to be removed, and the following style elements need to be added in the code of the plug-in:
sys.htp.p('</p><div id="mygallery" class="stepcarousel" style="overflow: hidden;"><div class="belt">');
In this line of code you see style=’overflow:hidden’. That is the line that actually had to be included in stepcarousel.js. This command hides the scrollbars.
- After you have uploaded the files, click on the Apply Changes button. The plug-in is ready and can now be used in a page.
- Go to the page where you want this stepcarousel to be shown.
- In the Regions section, click on the add icon.
- In the next step, select Plug-ins .
- Select Carousel .
- Click on Next .
- Enter a title for this region, for example Newscarousel. Click on Next .
- In the next step, enter the height and the width of the carousel. To show a carousel with three panels, enter 800 in the Width text field. Enter 100 in the Height text field. Click on Next .
- Click on the Create Region button.
- The plug-in is ready. Run the page to see the result.
How it works…
The stepcarousel is actually a div. The region type plug-in uses the function sys.htp.p to put this div on the screen. In this example, a div is used for the region, but a HTML table can be used also. An APEX region can contain any HTML output, but for the positioning, mostly a HTML table or a div is used, especially when layout is important within the region.
The apex_javascript.add_onload_code starts the animation of the carousel. The carousel switches panels every 3 seconds. This can be adjusted (Pause : 3000).
See also
- For more information on this jQuery extension, go to http://www.dynamicdrive.com/dynamicindex4/stepcarousel.htm.
