type: widget

release: TBD

status: in development - GitHub branch: tooltip

documentation: n/a

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

demo: http://view.jqueryui.com/tooltip/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
• http://plugins.jquery.com/project/Tooltip
• http://plugins.learningjquery.com/cluetip/demo/
• http://www.codylindley.com/blogstuff/js/jtip/
• http://cssglobe.com/post/1695/easiest-tooltip-and-image-preview-using-jquery
• http://www.lullabot.com/articles/announcing-beautytips-jquery-tooltip-plugin 
• http://craigsworks.com/projects/qtip
• http://ioreader.com/2007/05/15/flash-tooltips-using-jquery/ 

 

---

 

2 - Visual Design:

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

Options:

• content (String, Function, default: function that returns the title attribute)
• The content of the tooltip, as HTML, 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
• position (Options, default: { my: "left top", at: "left bottom", offset: "15 0" })
• Configuration for the Position utility, of option excluded (always configured by widget)
• tooltipClass (String, default: "ui-widget-content")
• additional classes to put on the tooltip
• can be CSS framework classes like ui-widget-header, ui-widget-content, ui-state-default, ui-state-hover, ui-state-active, ui-state-highlight, ui-state-error

Methods:

• open
• Programmatically open the tooltip, use close method to close it again
• close
• Programmatically close the tooltip, use open method to open it again

Events:

• open
• triggered whenever the tooltip is shown
• close
• triggered whenever the tooltip is hidden

 

---

 

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

 

    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)

 

     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/tooltip/tests/visual/tooltip/tooltip.html

 

---

 

6 - Open issues

 

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; no IE6 support at all (as far as I can tell by opening that page in IE6)
• 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.

 

Position issue:

http://forum.jquery.com/topic/tooltip-1-9m1-position-issue

caused by position, related to offset issue in jQuery core

http://dev.jquery.com/ticket/6483

 

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