Widget: Tooltip Dialog

Details

Implementing This Widget

Implement the Tooltip Dialog widget whenever you want to have a modal dialog that is rendered near the invoking element that is displayed when the mouse passes over or rests on that element. Further, implement this widget when you also want to make this functionality available to keyboard-only users and users of screen readers.

To implement the Tooltip Dialog widget:

The createTooltipDialog() function takes two arguments: the first is a reference to the DOM element that will trigger the tooltip to show up when it gets focus. The second is a config option that defines one required and two optional ID's, as well as three optional event handlers and an optional positioning function:

contentID* required

The id of the DOM node that you want to use as the content for this tooltip.

submitID

The ID of an element within the tooltip content area (probably a button) that, when clicked, should (1) invoke the onSubmit behavior if present, and (2) close the tooltip. Note: the button with this ID may have its own click handler independently of the tooltip. That will work, but if someone invokes tooltip submission by pressing enter, only the onSubmit function below will fire.

cancelID

The ID of an element within the tooltip content area (probably a button) that, when clicked, should (1) invoke the onCancel behavior if present, and (2) close the tooltip. Note: the button with this ID may have its own click handler independently of the tooltip. That will work, but if someone invokes tooltip cancelation by pressing escape, only the onCancel function below will fire.

onOpen

A function that fires when the tooltip first opens.

onSubmit

A function that fires when the tooltip is submitted. It can be submitted either by pressing enter while the tooltip has focus, or by pressing the button whose ID was passed in as 'submitID'.

onCancel

A function that fires when the tooltip is canceled. It can be canceled either by pressing escape while the tooltip has focus, or by clicking the button whose ID was passed in as 'cancelID'.

position

An optional positioning function. It takes two arguments: trigger is a reference to the element that triggered the tooltip, and tip is a reference to the tooltip itself. It returns an object with keys left and top, which are position values that get treated as CSS pixel values. The tip is absolutely positioned.

Expected Operation and Accessibility Features

The widget should appear when the element that triggers it upon receiving focus, whether by mouse or keyboard operation. Depending on the functionality implemented, an example would be pressing the Enter key when a button has focus, must function in the same way that clicking the button with a mouse would.

Validation and Developer Notes

In order to validate this control, you must ensure that all functionality is accessible, and this will differ depending on the unique configuration options that have been implemented. Additionally, it is important to verify browser type and version support via manual testing.

Example Implementation Reference

To view an implementation of this widget, see Tooltip Dialog widget example.

Source Code

The initialization function returns a function that can be used to deinitialize the tooltip, so that once a user has successfully invoked it they won't be bothered with it again. Refer to the JS below to see how this is used - the disable functions are invoked within the onsubmit functions to ensure that after the tooltip has served its purpose, it goes away:

function defaultPositionFunction(trigger, tip) {
 var triggerBounds = trigger.getClientRects()[0];
 var tipBounds = tip.getClientRects()[0];
 return {
   left: triggerBounds.left + triggerBounds.width + 10,
   top: triggerBounds.top + (triggerBounds.height / 2) - (tipBounds.height / 2)
 }
}