Creating Context-Sensitive Help on a Web PageBy Scott Mitchell
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
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?
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
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:
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:
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
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
visibility values. (The
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.
showHelpFloatWindow(windowID, contextSensitiveHTMLElement, horizPadding, vertPadding, goRight)- this function shows the help window whose
idattribute 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
hideHelpFloatWindowfunctions are used by the context-sensitive region's
onmouseoutclient-side events to show and hide a specific help window. The
getAscendingTopsfunctions are used internally by
I've used the
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 containingThese functions can be seen in their entirety in the live demo and can be downloaded from the end of the article.
<div>I use two recursive functions,
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.
getAscendingTops out of the way, let's take a moment to look at
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
setting the specified help windows
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.
hideHelpFloatWindow function simply resets the positioning-related CSS settings back to their initial
values, thereby hiding the help window:
Putting It All Together
<div> element for the floating help window, return to the
context-sensitive help area and complete the
onmouseout attributes like so:
Both of these functions pass in the value "MyHelpWindow" as their first input parameter because the
id attribute is set to "MyHelpWindow". Also, they pass in a reference to themselves (
to indicate the element by which the help window is displaying relative to. To see this script in action, check out the
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
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
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
The article Programmatically Creating Context-Sensitive Help on a Web Page examines how to overcome these shortcomings...
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.