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!


  1. I am getting the following error:

    * Business E-mail Addresss

    sorry, the content could not be loaded.

    when I hovered over the label of Business E-mail Address.

    I followed your jquery/AJAX item Help installation (created new labels, created application item, created application process, and entered text in the HTML header) and double checked the js and css references to ensure that it referencing the correct versions.

  2. Robert,

    Can you put an example on Email me as it would be easier to help you that way...


  3. Hi Dan,

    i ran into the same error.
    my guess is, that the url, which is generated in the "rel" element gets a bit clumsy
    using firebug i found this:

    as soon as i replace p_request=APPLICATION_PROCESS%3DGET_ARTIKEL_INFO
    and use the url in my brower, i get the expected response.

    with this "get.addParam('x01', $item.attr('for'));" in the sript part i try to pull the value for my on-demand-process. but i don't get it.

    any idea what is going wrong?
    thanks 4 ur help in advance


  4. Peter,

    Please place an example on


  5. Dan,
    The examples for "Label uses custom hover help" do not work. All I get is the "arrow with ?" and no help. Maybe it doesn't work with 4.1?

  6. Hi Robert,

    This post is really old now. APEX uses Ajax to display help out of the box (although it doesn't display it with clue tip).

    APEX 4.1 brought an enhancement that allows us to include the item help in the label template for an item so we can avoid an Ajax callout all together.

    I recommend making use of this new substitution string and combining that with a good tooltip plug-in, such as the one offered by the bootstrap library.

    I'd love to blog about how to do this but I don't have time right now...