Tooltip

Page history last edited by Scott González 1 week, 5 days ago

type: widget

release: 1.9

status: in development

documentation: http://docs.jquery.com/UI/Tooltip

discussion: http://forum.jquery.com/tag/jquery-ui-tooltip

demo: http://view.jqueryui.com/master/demos/tooltip/default.html

1 - Description:

A tooltip is a small overlay that sits over the main page that can be used to provide content or functionality that does not need to be always visible. Tooltips usually look like a small box or callout and can be trigged by a wide range of events. All tooltips should employ collision detection via the the Position utility and iframe protection via the bgiframe plugin.

General

All tooltips should be automatically protected by the bgiframe plugin to avoid z-index issues
The tooltip body should automatically expand to the width and height of the content

Maximum width option may need to be set in the CSS to keep tooltips from getting incredibly wide, you want it to wrap at some reasonable width (200-400px)

This could be a problem in IE6 as there is no max-width support. CSS Expressions as an alternative?

Maximum height option (scrollbars should appear if content height exceeds tooltip height)

Content

The native browser tooltip is always suppressed.
If no content is specified, the tooltip will grab the title attribute from the element and display the title content unformatted.
The content can be a string, including HTML markup, that will replace the title attribute
The content can be a function that either returns the HTML markup to display, or uses the provided callback to get asynchronous content (eg. via Ajax)

M1 Simple tooltip

This tooltip is used strictly for non-interactive content such as descriptions and text strings which cannot be directly interacted with by the end-user.
Default settings:

Show on mouseenter, delayed by 150ms (configurable, could use hoverintent for more intelligent behaviour)
Hide on mouseleave

Animations

Animations for the show and hide events should be optional to allow the tooltip to use any of the standard jQuery UI animated transition effects.
Defaults:

Show: fade effect
Hide: fade effect

Positioning

Relative to the cursor position

Static position: position tooltip based on position of cursor when called, do not re-position tooltip unless closed and re-opened (default)
Follow cursor position: constantly re-position tooltip as the cursor moves

Relative to the element

Can use any of the position placements: ex. left aligned and above parent; at the far right end of parent, above and to the right

Visual styles

The tooltip should be completely compatible with the CSS framework and Themeroller, including the connector graphic
Any custom class name including other framework container classes should be an optional parameter

widget-header, widget-content, state-default, state-hover, state-active, state-highlight, state-error can be passed in as an option so the tooltip can have different, themed styles

The option to add in the shadow class (when complete) would be a good option

Callout connector (Tip)

Created using polygonal CSS (http://www.filamentgroup.com/lab/image_free_css_tooltip_pointers_a_use_for_polygonal_css/) or Canvas/VML implementation. Or even a combination of both.
By default, it should have the ui-widget-content class
No callout connector: simple rectangular tooltip
Callout connector triangle: In two variants, filled and unfilled connectors

For any of these styles, the connector (if present) can appear in any of the standard 12 positions around the perimeter of the tooltip body:

Top edge, left aligned
Top edge, center aligned
Top edge, right aligned
Left edge, top aligned
Left edge, middle aligned
Left edge, bottom aligned
Right edge, top aligned
Right edge, middle aligned
Right edge, bottom aligned
Bottom edge, left aligned
Bottom edge, center aligned
Bottom edge, right aligned

A labs experiment for more accurate positioning: http://jquery-ui.googlecode.com/svn/branches/labs/tooltip-callout/index.html

Accessibility

The tooltip must be fully accessible (ARIA) and should provide update announcements to screenreaders to ensure that the tooltip content is read correctly when activated

Exisiting Plugins

2 - Visual Design:

3 - Functional Specifications/Requirements:

The .tooltip() widget can be applied to any element. The tooltip supports direct use on an element and delegation; the default options are set to work in both cases.

Focus takes precedence over hovering to determine the status of the tooltip. Focusing an element, then hovering over and out will result in the tooltip staying open. However, hovering over an element, then focusing and blurring, will result in the tooltip closing. The rationale for this is that if the user manually changes focus, then their mental focus has shifted, but if the user has just moved the mouse, it could be accidental or they could just be moving it out of the way.

Disabled tooltips should still prevent native tooltips. If you want to fall back to native tooltips, the tooltip widget should be destroyed instead of disabled.

Options:

content (Function, default: function that returns the title attribute)

The content of the tooltip, as HTML or jQuery object, returned by a function that will either

return the content to display
call another callback (passed as the first argument) with the content to display, to enable asynchronous operations

This is the right place to format the tooltip by adding elements (with extra classes) or any other changes

hide (Mixed, default: true)

TODO: document this somewhere (ui.widget docs?)

items (Selector, default: "[title]")

Selector to match elements that should show a tooltip
Default of [title] works with the content-default (get content from title attribute)

position (Options, default: { my: "left top", at: "left bottom", offset: "15 0" })

Configuration for the Position utility
of option defaults to the element showing a tooltip

show (Mixed, default: true)

TODO: document this somewhere (ui.widget docs?)

tooltipClass (String, default: null)

specify an additional class to add to the tooltip
NOTE: this should go away when we land the clases option (#7053)

Methods:

open( event )

Programmatically open the tooltip, use close method to close it again
event object is only necessary for delegated tooltips so the widget knows which element to show the tooltip for

close( event )

Programmatically close the tooltip, use open method to open it again
event object is only necessary for delegated tooltips so the widget knows which element's tooltip to close

Events:

open (event: focusin, mouseover)

triggered whenever the tooltip is shown
ui object:

tooltip (object[jQuery])

close (event: blur, mouseleave)

triggered whenever the tooltip is hidden
ui object:

tooltip (object[jQuery])

4 - Markup & Style:

4.1 Initial markup examples

(Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )

4.2 Recommended transformed HTML markup

(The HTML markup structure and classes that will be used by the scripts in the enhanced version)

4.3 Accessibility recommendation

The tooltip and its content must be fully keyboard accessible. For tooltips that only contain static content (such as text and images), this means the following:

The tooltip opens automatically when the trigger element receives focus. Because the mouse cursor is not used in this scenario, the tooltip should always be positioned adjacent to the trigger element.
The tooltip is closed automatically when the trigger element loses focus.
The user can close the tooltip manually by pressing the "Esc" key.
While the tooltip is showing, focus remains on the trigger element

Note: With this approach it will still be impossible for sighted keyboard users to open a tooltip for an element that is static itself (e.g. a tooltip that appears over a text paragraph or an image).

When removing the title-attribute from an element, add a "aria-describedby" attribute with the value referencing the id of the tooltip-element.

element.removeAttr("title").attr("aria-describedby", tooltipId);

The aria-describedby attribute needs also be added to input elements, when the label provides the tooltip.

This also requires the body to have a role="application" - where should that be handled?

The tooltip element needs .attr("role", "tooltip")

When hiding the tooltip, use .attr("aria-hidden", true), when showing it, use .attr("aria-hidden", false).

Note: When testing with NVDA, you may have to hit Insert+Tab to get the description for the element, in addition to the name. In some config/version it'll read it automatically.

4.4 CSS & Theme

(Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.)

5 - Latest version of plugin:

http://view.jqueryui.com/master/demos/tooltip/default.html

6 - Open issues

ARIA impl in IE

setting attr("title", "") prevents IE to expose Name attribute to screenreaders, so JAWS just reads the description. Removing it via .removeAttr("title") has the bad side effect, when done in mouseover event, of the native tooltip still showing up, with whatever title attribute value the element had when the event was triggered.

Italics means we'll ignore those issues for a first release. We need more information, context, experience or usecases to properly solve them.

While sticky tooltips are still described, we currently don't plan to implement them, as their interaction is too close to a dialog while lacking the proper interactions, eg. ESC to close wouldn't make sense for a tooltip. We may get back to this eventually.

Connectors aren't implemented, yet. There are various approaches and none are really satisfying so far. Some resources:

qTip implements connectors, uses canvas/vml. New 2.0 version implements polygonal CSS as soon in the previous examples also.
Filament Group's CSS triangles don't properly work in IE6 either, still, a prototype was implemented - it reads the theme colors and sets them on the triangle

Currently jquery.ui.tooltip.css defines a z-index of 999 for tooltips. There was a comment about this posing problems with Tabs (unable to reproduce those, see tests/visual/compound/tabs_tooltips.html ), so it may make sense to rethink that value. Though it can be easily fixed once we actually have more data on that issue.

How to handle tooltip width:

Don't restrict at all, just let the tooltip grow based on content

works for normal title-lengths
can get very big for long texts
makes it trivial to define in CSS (no override necessary)
could also be set in open-event when the content is present, to calculate something

Set a fixed width in theme

avoids tooltips getting too large
has to be overriden
usually either too big or too small, doesn't adapt to content

Set max-width in theme

anything smaller adapts to content
no/bad IE6 support
text-wrapping rather arbitrary, will probably look bad in a lot of cases when content is wider then the default max-width

How existing plugins handle it:

Jörn's tooltip doesn't specify a width, by default; user has to fix that where necessary, no known/reported issues with that
clueTip and qTip both set width via JavaScript as inline styles, not something we want to do; at least qTip has also min/max width options, probably also for height