To read the article online, visit http://www.4GuysFromRolla.com/webtech/081606-1.shtml

Creating Context-Sensitive Help on a Web Page

By Scott Mitchell


Introduction
When building report screens for a web application, there are often certain snippets of the report whose meaning may not be crystal clear to all users. Reports may be chalk full of acronyms or abbreviations that be like a second language to the report's primary users, but gobbledygook to upper-level managers or executives who may occassionally scan the online reports. Or your report might use special color-coded text, image files, or icons to express information, and these graphical cues might not be straightforward to all who would read the report.

In such situations, I find it helpful to provide context-sensitive help. Context-sensitive help is help that provides the user with a terse explanation or description for a particular element or state in the application. Tooltips are the canonical example, allowing a user to simply hover their mouse over a particular user interface element to learn about its purpose or functionality. Returning to our earlier report example, context-sensitive help can be used to spell out those potentially confusing acronyms, or disambiguate what the different color-codings or images in the report mean.

The HTML standard provides the title attribute to virtually all HTML elements, and most browsers display the title as a tooltip when the user's mouse hovers over the element in question. (To demonstrate, hover your mouse over the following <span> tag, whose title attribute has been set to "Look at me, I'm a tooltip!": Hover your mouse over me...) Unfortunately a tooltip can only display a relatively short text string. But what if you want to display richer help, one with different text sizes and colors that may include images?

To overcome the limitations of the tooltip, I have long used a context-sensitive help system that, with a short line of JavaScript, will display a floating help window when the user mouses over a pre-defined region on the screen. The help displayed in this window can contain any HTML content, including richly formatted text and iamges. (See a live demo!) Read on to learn how to add such rich context-sensitive help to your web pages!

Performing an Action When the User Mouses Over a Particular HTML Element
The HTML standard defines a number of client-side events that can be used to perform some action in response to a user's action. The onmouseover and onmouseout events can be used to perform some action when the user's mouse moves over some region and when it moves off. For context-sensitive help, we want to display the associated help window when the user moves over a region (such as an acronym or image in a report) and hide this window when the user's mouse leaves the region.

For example, context-sensitive help could be applied to an HTML button using the following markup:

<input type="button" value="Submit"
       onmouseover="showHelpWindow"
       onmouseout="hideHelpWindow" />

Displaying a Floating Help Window
When the user mouses over a pre-defined region, we can show the help window in one of two places - in some fixed location on the screen (such as in a floating window at the top, center of the page), or near the user's mouse pointer. Let's look at accomplishing the latter approach. In order to show a floating window, we first need to add one to the page. In my projects, I've often used a <div> element positioned off screen (using absolute positioning) that contains an <iframe> within it for the floating help window. The <iframe> points to a separate, stand-alone HTML file that contains the help markup to display. When the context-sensitive region is moused over, the <div> element is positioned next to the user's mouse and the <iframe> is loaded with the appropriate help file. (For more information on positioning elements with CSS, see the CSS Layout Tutorial.)

The following illustrates such a <div> element (with the <div> element's style information moved to a CSS class:

<style>
.HelpWindow
{
	z-index: 999;
	position: absolute;
	top: -999px;
	left: -999px;
	display: none;
	visibility: hidden;
	
	width: 300px;
	height: 250px;
	
	... feel free to add additional style settings here ...
}
</style>

<div id="MyHelpWindow" class="HelpWindow">
  <iframe frameBorder="0" height="100%"
          src="HelpPage.htm"></iframe>
</div>

The CSS settings defined in the HelpWindow class indicate that the window is, initially, hidden from view and that it is to be positioned absolutely. The <iframe> element's src attribute points to the HTML page that contains the help content to display. When the user mouses over a context-sensitive help region, we'll need to reference this window by its id attribute value and update its top, left, display, and visibility values. (The width and height CSS settings dictate the help window's width and height. These can be set to whatever values you deem necessary and do not need to be changed when mousing over or out of the context-sensitive region.

There are four JavaScript functions to display and hide a context-sensitive help window:

  • showHelpFloatWindow(windowID, contextSensitiveHTMLElement, horizPadding, vertPadding, goRight) - this function shows the help window whose id attribute is equal to the passed-in windowID value. It places the help window next to the HTML element specified via the second input parameter (contextSensitiveHTMLElement) - to the right of the element if goRight equals true, and to the left otherwise. The padding between the contextSensitiveHTMLElement element and the help window can be specified via the horizPadding and vertPadding input parameters.
  • hideHelpFloatWindow(windowID) - hides the specified help window
  • getAscendingLefts(elem) - given a specified HTML element, this function determines the pixel position of the left of elem
  • getAscendingTops(elem) - given a specified HTML element, this function determines the pixel position of the top of elem
The showHelpFloatWindow and hideHelpFloatWindow functions are used by the context-sensitive region's onmouseover and onmouseout client-side events to show and hide a specific help window. The getAscendingLefts and getAscendingTops functions are used internally by showHelpFloatWindow.

Examining the JavaScript Functions
I've used the getAscendingLefts and getAscendingTops functions in previous articles here on 4Guys. For example, in the article Creating a Tabbed Interface for Displaying Parent/Child Data, I explained:

To determine the top and left coordinates of the containing <div> I use two recursive functions, getAscendingTops(element) and getAscendingLefts(element), which walk up the passed-in element's set of containing HTML element, summing up their top and left offsets. A more thorough discussion of this technique can be found at Determining the Location of a Nonpositioned Element, and is the technique utilized by my free, open-source ASP.NET menu control, skmMenu.
These functions can be seen in their entirety in the live demo and can be downloaded from the end of the article.

With getAscendingLefts and getAscendingTops out of the way, let's take a moment to look at the first two JavaScript functions. showHelpFloatWindow starts by referencing the windowID element passed in and updates its CSS settings. It determines the absolute position for the top and left pixels through the getAscendingLefts and getAscendingTops functions, setting the specified help windows left and top based on the context-sensitive region's upper left corner, the values of the horizontal and vertical padding, and whether or not to display the window to the right or left.

function showHelpFloatWindow(windowID, obj, horizPadding, vertPadding, goRight)
{
   var w = document.getElementById(windowID);
   if (w != null)
   {
         w.style.display = 'block';
      w.style.visibility = 'visible';
      w.style.top = getAscendingTops(obj) + vertPadding;
      if (getAscendingTops(obj) + vertPadding < 0) w.style.top = 0;
      if (goRight == true)
         w.style.left = getAscendingLefts(obj) + obj.offsetWidth + horizPadding;
      else
      {
         w.style.left = getAscendingLefts(obj) - horizPadding;
         if ((getAscendingLefts(obj) - horizPadding) < 0)
            w.style.left = getAscendingLefts(obj) + obj.offsetWidth + horizPadding;
      }
   }
}

The hideHelpFloatWindow function simply resets the positioning-related CSS settings back to their initial values, thereby hiding the help window:

function hideHelpFloatWindow(windowID)
{
  var w = document.getElementById(windowID);
  if (w != null)
  {
    w.style.display = 'none';
    w.style.visibility = 'hidden';
    
    w.top = -999;
    w.left = -999;
  }
}

Putting It All Together
With these JavaScript functions added to the web page (or better yet, in a separate JavaScript file) along with the <div> element for the floating help window, return to the context-sensitive help area and complete the onmouseover and onmouseout attributes like so:

<input type="button" value="Submit"
       onmouseover="showHelpFloatWindow('MyHelpWindow', this, 10, 20, false);"
       onmouseout="hideHelpFloatWindow('MyHelpWindow');" />
[View a Live Demo!]

Both of these functions pass in the value "MyHelpWindow" as their first input parameter because the <div> element's id attribute is set to "MyHelpWindow". Also, they pass in a reference to themselves (this) to indicate the element by which the help window is displaying relative to. To see this script in action, check out the live demo.

A Cross Browser Tooltip JavaScript Library
Alert reader Mani wrote in to share a free, cross browser JavaScript tooltip library. See A Cross Browser Tooltip JavaScript Library for more information!

Looking Forward...
At this point, the context-sensitive help system is rather simple and has some downsides. First, all of the help is done entirely through static markup. Want to add a different help window? You need to add the appropriate <div> / <iframe> and the onmouseover and onmouseout statements to the context-sensitive region. However, many times we want to inject these help windows programmatically from templates in an ASP.NET data Web control or from the code-behind class itself. Additionally, if you download the code and play around with it you may find that if you set the help window's height too small, the help text is clipped. While there is a scrollbar in the <iframe>, it can't be reached because moving the mouse to the scrollbar causes the onmouseout event to fire, thereby hiding the window! Along a similar vein, if the help window contains a hyperlink you can't click it, as mousing off of the help region causes the help window to instantly disappear!

These issues are discussed in: Programmatically Creating Context-Sensitive Help on a Web Page.

Improving the Context-Sensitive Help System...
This article aims to simply lay the ground work for creating a context-sensitive help system and, as such, has a few shortcomings. Most noticeably, the help window appears immediately when mousing over its associated region and disappears immediately after mousing out of that region. This behavior introduces two usability issues: first, when moving the mouse over the screen, if you happen to pass over a help region the help window appears, which can be jarring; second, if a help window contains links or is lengthy enough to require scrolling, when attempting to move the mouse from the help region to the help window, the mouse leaves the help region and the help window disappears.

In addition to these two end user usability problems, the context-sensitive help system isn't very user friendly for us, the page developer. All of the script and <div> and <iframe> elements needed to be manually added to the web page to define the help windows and the onmouseover and onmouseout event handlers for the help region. Ideally, all of the necessary script and markup could be added programmatically, with a single line of code from the ASP.NET code-behind class.

The article Programmatically Creating Context-Sensitive Help on a Web Page examines how to overcome these shortcomings...

Conclusion
HTML's title attribute makes it possible to add tooltips for a variety of HTML elements in order to provide context-sensitive help. However, tooltips are limited to displaying a short text message and lack the ability to enjoy rich formatting, images, colors, and so on. In this article we saw how to create our own tooltip-like system capable of displaying richer help screens once a user has moused over a pre-defined region on the screen.

Happy Programming!

  • By Scott Mitchell


    Attachments

  • View a Live Demo!
  • Download the Live Demo Code
  • Read Programmatically Creating Context-Sensitive Help on a Web Page

  • Article Information
    Article Title: Creating Context-Sensitive Help on a Web Page
    Article Author: Scott Mitchell
    Published Date: Wednesday, August 16, 2006
    Article URL: http://www.4GuysFromRolla.com/webtech/081606-1.shtml


    Copyright 2017 QuinStreet Inc. All Rights Reserved.
    Legal Notices, Licensing, Permissions, Privacy Policy.
    Advertise | Newsletters | E-mail Offers