Skip to end of metadata
Go to start of metadata

Purpose

A tooltip (synonym = hover help) provides context-sensitive help, presenting a small "tid-bit" of information to the user,  "just in time", and in a way that doesn't get in the way of doing tasks.  Tooltips don't take the user out of their present context (don't open another view to manipulate and potentially get lost in).  Tooltips are not visible at all times, they don't take up real-estate on screen, they don't trap the user in a mode that they then have to exit from. 

The tooltip construct is part of the overall Help Framework and is used in the new Error Handling.

Detailed Description

Research has shown that users often don't notice helpful text on a densely laid-out page, so the tooltip strategy for field-level and section-level help offers the application designer a "just-in-time" help capability.

There will be no help icon in the UI to signal that there is a tooltip associated with an element.  But tooltips have become standard fare in rich applications, and users now actively explore user interfaces looking for these relevant 'nuggets' of information (tooltips and other) when they use a new application or infrequently use it.

Tooltips appear when the user hover over the UI element (or on focus for keyboard users) and disappears when user moves out of the contiguous space formed by the trigger element and the tooltip content itself.  They can include simple text only or can also include links and other controls that the user can interact with.   See more details in the requirements section below.

Usage Scenarios

Usage Scenario One:

User isn't quite sure if her interpretation of what to enter into a particular field is correct.  She notices a tooltip opens when she hovers over the field label.  Reading the additional short tip provided in the tooltip makes her feel more confident that her initial interpretation was correct, so she enters her choice into the field.

Usage Scenario Two:

User isn't quite sure if his interpretation of what to enter into a particular field is correct.  He notices a tooltip opens when he hovers over the field label.  Reading the additional short tip provided in the tooltip still doesn't clarify his questions, but he notices there is a link provided in the tooltip, for additional information.  He clicks on the link and notices that another smaller window opens on top of the application.  He reads through the additional information and now thinks he understands the choices.  He moves the help window outside of his current application view so he can view both windows side-by-side as he interacts with the form.  (He can close the help window at any time.)

Usage Scenario Three:

User wonders what is the need for completing a section in a form, that is for scheduling batch changes.  She doesn't know if she really need to do that, and she notices there is a help icon associated with the section heading.  When she hovers over the help icon, she sees a tooltip that states "Display help for Scheduling Batch Changes".  She selects the help icon and another smaller window opens on top of the application. She reads through the additional information and now thinks she understands that she can just accept the defaults in this section, that were set up for her department.  She closes the help window and moves on to the next section.

Usage Scenario Four:

User enters an incorrect value in a field which has client-side validation behavior.  As soon as he exits that field to continue completing the form, he notices that an error tooltip has popped up for the field he just exited.  He reads the error message and realizes he has a typo (spelling mistake) in the field.  He goes back, corrects the spelling, and moves on.  The tooltip disappears when he exits the field, so he feels confident that all is now ok with that entry.

Usage Scenario Five:

User completes a form with 20 required fields.  She submits the form, but then notices that she is back at the top of the form in a summary of errors, that shows that she has 2 errors on the form.  She clicks on the link to go to the first field that has an error, and her focus moves into that field.  An error validation message tooltip opens above the field when the field gets focus.  The tooltip provides her with the error message and tips for correcting it.  She enters a new value into the field, that she thinks will be correct.  The tooltip closes, making her feel like all is now ok with that field.  She moves focus to the 2nd field that was flagged and notices a similar tooltip has opened with other helpful information on why her original entry is incorrect.  She fixes that field, the tooltip disappears, and she resubmits the form.

Mocks and Diagrams

The Help Tooltip enables applications to deliver context-sensitive help for individual fields and controls, virtually, for any user-manipulable control - without cluttering the page.  The tooltip appears on hover (and on focus for keyboard users) and disappears when the user moves outside of the contiguous area formed by the trigger element and the tooltip content.  It also closes if the user activates a link contained within the tooltip content. 

Below is a low-fidelity example of a tooltip that contains only text (specific visual treatment yet to be determined):

Below is a low-fidelity example of a tooltip that contains richer content that the user can interact with (specific visual treatment yet to be determined):

Performance

If applicable, list expectations for performance (optimal and worst cases would be fine, give time in seconds):

References

Tooltips have become a common user interface aspect that users expect across software and web user interfaces.  See below for examples:

Requirements Listing

Primary:
  1. The triggering elements that will be supported are user-manipulable controls and field labels.  Examples include:
    • Highest priority:
      • Field labels - for example for input fields and drop-down controls. 
      • Input fields (for the error message tooltips) - this use of the tooltip control disambiguates the help tooltip from the error message tooltip, which is associated with the input field itself, not with the field label -  see the KRAD Error Message Architecture.
      • Fieldset legends:
        • checkbox control
        • radio button control
      • buttons (including help icons)
      • tab labels (the tab list items)
      • headers
      • links
    • Secondary:
      • tree item labels (the tree nodes)
      • expand/collapse controls
      • sort controls
  2. Placement:
    1. The tooltip appears contiguous to the trigger element, it does not occlude it. 
    2. Assuming sufficient space in the viewport, there is a default placement in KRAD = the tooltip appears above and to the right of the trigger element, with the left margin of the tooltip starting at the horizontal center of the trigger element, with the bottom of the tooltip being just above the trigger element.
    3. This default can be changed by a language setting and can be over-ridden by an application if necessary (by application design considerations).  
    4. The default placement will also be automatically/dynamically re-adjusted to ensure best fit in the viewport and to avoid occluding the trigger element when resizing the view.   
  3. Focus:
    1. The tooltip appears when the focus moves to the trigger element and when hovering over the trigger element with the mouse pointer.
    2. The tooltip remains open as long as the focus or hover position remains on the trigger element or anywhere within the tooltip construct itself.  The user can move the mouse within the contiguous space that is occupied by the trigger element and the tooltip itself, without the tooltip closing. 
    3. When the focus moves off the contiguous space occupied by the trigger element and the tooltip, or when the user selects a link from within a tooltip, the tooltip closes.  
  4. Timing: 
    1. There is a default timing in KRAD for appearance and disappearance (upon hover on and upon moving off - the precise default timings are tbd). The defaults can be over-ridden if necessary by an application (by application design considerations).
    2. The tooltip does not 'fade' after a timed interval, it remains open (see focus section above).   Note that if we have fade/timing, the user must be able to set a 'sticky' preference or to change the default fade/timing, for accessibility reasons.
  5. Rich message capability:
    1. All tooltips must be able to include text and area styling effects (fonts and font effects, colors, spacing, rounded borders, gradients, shadows).  There will be a default Kuali Rice style.  An application can define and substitute a different default style.
    2. Tooltips must also be able to include controls, such as links and buttons.
  6. Accessibility aspects:
    1. Appropriate ARIA tagging is included to ensure announcements are available to assistive technologies, such as screen-readers, when a tooltip is activated.
    2. When users over-ride the default OS or browser settings in order to achieve high contrast or larger font sizing, the tooltips must inherit these aspects gracefully.
    3. If we have fade/timing (this is explicitly ruled out in the materials above), the user must be able to set a 'sticky' preference or to change the default fade/timing, for accessibility reasons.
  7. Tooltip "mode":
    1. Both the validation messaging and the help framework have dependencies on the tooltip construct. The tooltip must be capable of differentiating whether it is being called for displaying help or called for displaying validation messages. This is because the visual/stylistic treatment and behavior will differ across these two uses. 
  8. Server-side validation message tooltip behavior mirrors that of the help tooltip behavior, documented above.  But there are the following differences for client-side validation messages, documented in the validation messages requirement:
    1. If there is no server-side validation message tooltip already associated with the same field (the vast majority of the cases):  A client-side validation message tooltip pops-up immediately upon exiting a field, or other control, in a client-side validation error condition, and fades after a period of time (time length is tbd). It does not require hovering or field focus in order to be displayed. But after fading, upon hover or re-focus on the field or control, it re-opens.
      1. When a client-side validation error is corrected (in the vast majority of cases), the tooltip closes upon exiting the field, and any other client-side visual indication disappears.
    2. If there is a server-side validation message already associated with the same field, the client-side validation error is added to the top of the server-side error message, in the same tooltip - different visual treatment will be applied (precise treatment tbd).  And the tooltip behaves as a server-side tooltip, documented above.
      1. When the client-side error is fixed, it is removed from the tooltip. The tooltip continues to behave as a server-tooltip does (it remains open till the user moves out of the field).
Summary Comments:
  • This tooltip construct is not the UI construct intended to display the content associated with the help icon (page-level help), though the help icon can have an associated tooltip as well.   For example, when the user hovers over or moves focus to a help icon, brief summary text should be displayed as a tooltip for the help icon itself. In the example of a help icon, this doesn't include the help text itself, but a brief description of the type of help that activating the help icon (clicking via mouse or using the Enter key with the keyboard) will produce. Examples: "Display help for this page". Activating the help icon will bring up the help content in a new browser window - see the KRAD Help Framework for information on how these elements fit together.)See the overall KRAD Help Framework.
  • The treatment and behavior for the help tooltip is different from the error messaging tooltip (for server-side and client-side error messaging). Visual treatment will differ, providing visual cues that users will be able to use to predict the difference in behavior.  See the Error Messaging.

Dependencies

List any functional or technical work that must be completed before work on this item can begin:

  1. Assess & select which jQuery or other tooltip plug-in to use.
  2. See also the Help Framework dependencies.
  3. See also the Error Message Architecture dependencies.

Issues

Work can proceed before the following is resolved, as these will go into the other later 2.2 requirement that is related to keyboard support.  The below are documented here also because of the context:

Functional:
  1. Keyboard support model for our current model -- documented above and described below: 
    The error tooltip is currently specc'd to appear on focus in the field, and to remain visible while the user is interacting with the field.
    On the other hand, the help tooltip is currently specc'd to appear on hover on the field label and would not be visible while the user is interacting with the field. 
    1. If we remain with the current plan, to disambiguate the help from the error tooltip by associating the help tooltip with the field label rather than the entry field, would it be cumbersome for each label to be a tabstop (to support keyboard users / focus)?
    2. Or is there any other standard model that would work better for keyboard users when the help tooltip is associated with labels, headers, titles, etc.?
  2. Related to this - Research the implications if we would show both validation message and help content when an input field has focus - instead of our current model,:
    1.  If we instead mapped both tooltips to the input field, would it be cumbersome to always show help when a field has focus?
    2. And if we mapped both tooltips to the input field, would it be problematic to not be able to view the field's help tooltip while in an error condition? Or would it be cumbersome to append the help content to the bottom of the error tooltip?
Technical:
  1. item
  2. item

QA or Regression Testing Plan

List steps needed to test the basic functionality of this update, enhancement, bug fix

  1. See QA / Regression Testing Plan associated with the Validation Messaging Framework.
  2. See QA / Regression Testing Plan associated with the Help Framework.

Checkoff

Functional Analysis Complete? No (completed by SME)

Needs Review by KAI? No (completed by SME)

Technical Analysis Complete? No (completed by DM)

Needs Review by KTI? No (completed by DM)

Estimate: 60 hours (completed by DM)

Technical Design: Tooltip (completed by DM)

Jira: KULRICE-6673 

Final Documentation: Link Here (completed by DM)

  • No labels

4 Comments

  1. If a tooltip is set on a field's control - top and right may occlude information necessary to finishing that field mainly the instructions and label, pointing this out.  Also, I don't see explicit mention that this will be an option available on all components - when feasible - but our immediate needs are with help icons and with buttons.  Tooltips showing and hiding should also be controllable through spEL as well through a showTooltip property for cases when showing a tooltip is no longer relevant based on page/field states.

    1. Current plan is that the help tooltip is set on the field's label, not the field's control itself. But that the error tooltip is set on the field's control. Assume top/right for now, but we can work with the plug-in's defaults to determine best initial position for error tooltips. (Each plug-in also comes with their own algorithms for managing dynamic re-positioning based on window size.)

  2. A tooltip plugin that was recommend by the MyPlan team is:

    http://www.vegabit.com/jquery_bubble_popup_v2/

    1. Yes, that is the first one in the list of references above – Brian looked at it and briefed Samuel on the fact that he liked what he saw in it overall, had questions about 2 aspects (with no time to pursue to answers), so Samuel can assess.