type: widget

release: 1.8+

status: in development

documentation: n/a

demo: n/a

 

 

---

 

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 and iframe protection via the Position utility. 

 

• General
  • All tooltips should be automatically protected by the stackfix 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 default browser tooltip is always suppressed.
  • If nothing is specified, the tooltip will grab the title attribute from the parent 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

 

• M2 Sticky tooltip - isn't this just a very lightweight dialog?
  • This tooltip allows for interaction within the tooltip by the end-user for things like forms, links and buttons.
  • Close [x] icon at top right corner allows the user to close the tooltip when clicked
  • Default settings:
    • Show on Click
    • Hide on "Blur" (User clicks elsewhere on the page)
  • Optional settings:
    • Open on mouseOver instead of onClick.
      • In this case, an extended mouseOver is used and does not close the tooltip immediately when the user mouses off the originating element.
    • Auto close when a user mouses off the tooltip after a specific time delay

 

• 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, no not re-position tooltip unless closed and re-opened (default)
    • Follow cursor position: constantly re-position tooltip as the cursor moves
  • Relative to the parent
    • 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 accutare 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: functions that returns the title attribute)
  • The content of the tooltip, as HTML
  • Can be a string to display
  • Or 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 title by adding elements (with extra classes) or any other changes
• position (Options, default: { my: "left top", at: "left bottom", offset: "15 -12" })
  • Configuration for the Position plugin, 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 uwidget-header, widget-content, state-default, state-hover, state-active, state-highlight, state-error

Methods:

• n/a

Events:

• n/a

 

---

 

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

 

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

 

     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://jquery-ui.googlecode.com/svn/branches/dev/tests/visual/tooltip/default.html

 

---

 

6 - Open issues being discussed

 

Collision detection (implemeneted via Position) will change the resulting position of the tooltip. If the user specifies that he wants the tooltip on the top right, with the arrow placed accordingly, that has to be reintepreted after a collision. We need to figure out the API that lets the user specify the tooltip and arrow position in the first place, as well as influencing the collision result.

Currently the Position plugin doesn't provide any information about changes due to collision detection, so the Tooltip has to figure out itself where the element actually ended up at.

 

Ajax tooltip: Cancel the request or at least ignore the response if it happens after close.

 

IE6 rendering of callout:

 

---