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.
- Go to Shared Components | User Interface | Plug-ins.
- Click 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 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.
- 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;[render_simple_tooltip.sql]
- 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 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.
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.
- 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 ends with the return of
l_result. This variable is of typeapex_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. - Click the Create button.
- The next step is to define the parameter (attribute) for this plug-in. In the Custom Attributes section, click 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 to text.
- Click the Create button.
- In the callbacks section, enter render_simple_tooltip into the render function name text field.
- Click the Apply changes button.
- The plug-in is ready now. 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 available plug-ins. Select the one we just created, tooltip. Click Next.
- In the item name text field, enter a name for the item, for example tt_item.
- In the region select list, select the region you want to put the item in. Click Next.
- 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.
- In the last step, leave everything as it is and click the Create item button.
- You are ready now. Run the page. When you move your mouse pointer over the new item, you will see the tooltip.
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, this makes this a text item with a tooltip, replacing the normal text item.
The tooltips shown in this recipe are rather simple. You could make it 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 the plug-ins link.
- Click the tooltip plug-in you just created.
- In the source section, replace the code with the following code:
function render_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;
[render_tooltip.sql]
--Register the javascript and CSS library the plug-in uses. 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 ); [render_tooltip.sql]
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;
[render_tooltip.sql]
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. $().bt 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 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 the upload button.
The files and their locations can be found as follows:
Library
Location
jquery.bgiframe.min.jsjquery.bt.min.jsjquery.easing.1.3.jsjquery.hoverintent.minified.jsExcanvas.jst-0.9.5-rc1other_libsexcanvas_r3
- If all libraries have been uploaded, the plug-in is ready. The tooltip now looks quite different:
For more information on this tooltip, go to: http://plugins.jquery.com/project/bt.