Saturday, June 7, 2008

AJAX Item Help

As most people know, items in ApEx have a "help" built in. When the end user of your application clicks on an item's label, a new window opens displaying that item's help text. I wanted to see if I could achieve this without a new window. After a little digging I found a great jQuery plugin called clueTip which can be set to use another plugin called hoverIntent. Information about the products can be found at the following URLs.

To view an example of an item that has the standard popup help and one that has "Hover Help" side by side, see the following example.

Here are some simple instructions on how to get it working in ApEx...

  1. Install jQuery in ApEx.
  2. Download cluetip from the links above. Create a new folder called cluetip in your i/jquery directory (created in step 1) and unzip the contents of the zip file into that location.
  3. Donload hoverIntent from the links above. Save the contents in a file called jquery.hoverIntent.js and save that file in a new folder named hoverintent in the i/jquery directory.
  4. Enter the following in the HTML Header of the page where you would like to use hover help. If you would like to use hover help on multiple pages, the link and script elements can be placed in the page template instead of the individual page.
    <link href="i/jquery/cluetip/jquery.cluetip.css" type="text/css" rel="stylesheet" />
    <script src="i/jquery/dimensions/jquery.dimensions.js" type="text/javascript"></script>
    <script src="i/jquery/hoverintent/jquery.hoverIntent.js" type="text/javascript"></script>
    <script src="i/jquery/cluetip/jquery.cluetip.js" type="text/javascript"></script>
    <script type="text/javascript">
          var pageID = $('#pFlowId').val();
          $('.hoverHelp').each( function(i) {
                var $item = $(this);
                var get = new htmldb_Get(null,pageID,'APPLICATION_PROCESS=ITEM_HELP',0);
                get.add('TEMP_ITEM', $item.attr('for'));
                $item.attr('rel', get.url());
                $item.attr('relTitle', $item.html());
                return true;
             arrows: true,
             titleAttribute: 'relTitle',
             hoverIntent: {    
                sensitivity: 2,
                interval: 200,
                timeout: 0
  5. Create an application item called TEMP_ITEM
  6. Create an application process named ITEM_HELP that fires ondemand with the following code:
       SELECT *
       INTO l_item_rec
       FROM apex_application_page_items
       WHERE application_id = :APP_ID
       AND item_name = :TEMP_ITEM;
       htp.p ('<div style="padding-right: 4px; padding-left: 4px; padding-bottom: 4px; margin: 4px; padding-top: 4px"><span class="instructiontext">' 
          || l_item_rec.item_help_text 
          || '</span></div>');
  7. Create two new label templates called "Optional Label with Hover Help" and "Required Label with Hover Help". For the Optional Label with Hover Help, set the "Before Label" value to:
    <label class="hoverHelp" style="cursor: help" tabindex="999" for="#CURRENT_ITEM_NAME#" rel="" reltitle="">
    Then set the "After Label" value to:
    For the Required Label with Hover Help, set the "Before Label" value to:
    <label class="hoverHelp" style="cursor: help" tabindex="999" for="#CURRENT_ITEM_NAME#" rel="" reltitle="">
    <img alt="" src="#IMAGE_PREFIX#requiredicon_status2.gif" />
    Then set the "After Label" value to:

    The important attributes in both label elements are rel and relTitle. Both are empty when the page is loaded but are filled with the URL needed for the AJAX call and the label name respectively as soon as jQuery can do so.

  8. Finally create some items and set the templates for the labels to the newly created templates and populate some help data for the items. Then run the page and see the new help!