Working with the Spry Tooltip Widget

The Spry Tooltip widget allows users to mouse over page elements and expose addition information/markup. This additional content will disappear after the mouse moves away. This document describes how to implement a Spry tooltip widget and how to control its functionality.

About Spry widgets

A Spry widget is a page element that combines HTML, CSS and JavaScript code to enable user interaction. A Spry widget is made up of the following parts:

Widget structure: An HTML code block that defines the structural composition of the widget.
Widget behavior: JavaScript code that controls how the widget responds to user-initiated events.
Widget styling: CSS code that specifies the appearance of the widget.

The Spry framework supports a set of reusable widgets written in standard HTML, CSS, and JavaScript code. You can easily insert these widgets—the code is HTML and CSS at its simplest—and then style the widget. The behaviors in the framework include functionality that lets users show or hide content on the page, change the appearance (such as color) of the page, interact with menu items, and much more.

Each widget in the Spry framework is associated with unique CSS and JavaScript files, available on Adobe Labs. The CSS file contains everything necessary for styling the widget, and the JavaScript file gives the widget its functionality. The CSS and JavaScript files associated with a given widget are named after the widget, so it's easy for you to know which files correspond to which widgets. (For example, the files associated with the Accordion widget are called SpryAccordion.css and SpryAccordion.js).

About Spry widget accessibility and JavaScript degradation

It is critical to the usability of the widget that it be accessible when following established web navigation conventions. You can't assume that the user is using a mouse, and therefore Adobe has taken steps to ensure that all aspects of the currently available widgets are accessible through the keyboard. In the Accordion widget, for example, you can use up and down arrow keys to open content panels. Adobe encourages all widget developers to build in this kind of functionality.

It's also impossible to control the end user's environment. Adobe develops widgets to ensure that when JavaScript is turned off, all the content of the widget is still available on the screen. While this will most likely affect the page layout, it is more important that the content of the widget still be available, especially when working with disclosure widgets. Adobe ensures that default CSS states do not set visibility to hidden, and that HTML code is not positioned off screen.

Before you begin

Prepare your files

Before you add Spry widgets to your web pages, download and link the appropriate files.

Locate the Spry ZIP file on the Adobe® Labs website.
Download and unzip the Spry ZIP file to your hard drive.
Open the unzipped Spry folder and locate the widgets folder. This folder contains all of the files necessary for adding and styling Spry widgets.
Add widget files to your website by doing one of the following:
- Copy the widgets folder and paste or drag a copy of it to the root directory of your web site. If you do this, you will have all of the files necessary for all of the widgets that Spry supports.
- Create a folder in your website (for example, a folder called SpryAssets), open the widgets folder, and copy only the files or folders that pertain to the widgets you want to add. For example, to add only an Accordion widget to your web pages, copy the accordion folder, or the SpryTooltip.js and SpryTooltip.css files.
Note: If you drag the original widgets folder or individual files out of the unzipped Spry folder, the demos in the Spry folder won't work properly. Be sure to copy and paste to your website instead of dragging.
When the correct widget JavaScript and CSS files are part of your website, you are ready to link them and add Spry widgets to your pages. For specific instructions on adding each widget to a page, see the individual widget sections.

Working with the Tooltip widget

Tooltip widget overview and structure

A tooltip widget consists of:

The tooltip container. This element contains the markup to be displayed when the tooltip is activated.
The page element(s) that activates the tooltip.
The constructor script. This javascript tells Spry to create the tooltip functionality.

The tooltip is a relatively simple widgets. Here are some ideas to keep in mind about the tooltip.

Any open tooltip will close before the next one opens.
The tooltip will persist while the mouse is in the trigger area.
There should be no limitations as to which tags can be triggers and what can be tooltip content.
By default, the tooltip opens 20 pixels down and right of the cursor. offsetX and offsetY are used to set a custom opening point. These are measured from the cursor, not the default location.
Both trigger and tooltip markup should come before the constructor script.
There is currently no way to have a tooltip open onLoad.

Here is an example of a basic tooltip widget.

<p>The master/detail <a href="#" id="relationship">The trigger</a> is established by ... </p> 
<div id="firstFixed">This is the tooltip</div>
 
<script type="text/javascript">	
   var static_tooltip = new Spry.Widget.Tooltip('firstFixed', '#relationship' , {closeOnTooltipLeave: true, hideDelay: 1000});
</script>

In the above example, the <a> with the id="relationship" in the first line is the trigger element. When the user mouses over this tag, the tooltip will show.
The <div> with the id="firstFixed" is the tooltip content. This will show when the user mouses over.

The constructor script works as follows.

The var defines the widget name. In this case, the name of the widget is "static_tooltip".
Within Spry.Widget.Tooltip, the required arguments are:
- ID of the tooltip content: "firstFixed"
- CSS selector of the trigger element. This can be a class, a HTML Tag, ID or combination. In this sample, we use an id CSS selector: "#relationship".
- Options: These define options for the tooltip, such as how long to display the tooltip and where to place it. Options are described in detail later in this document.

The Spry Tooltip widget depends on the ID and CSS selectors of the elements to order to function correctly. The markup used for or within the elements does not matter. The trigger can be anything and the content can be anything. Note that some additional steps are needed in order to combine this widget with Spry Data.

CSS code for the Tooltip Widget

The tooltip widget does not require much CSS. We use javascript to show, hide and position the tooltip. All other look and feel of the widget itself is done with standard CSS techniques, as your page requires. The only rule that the default CSS file contains is a workaround for IE6 so that the tooltip appears above form elements or flash objects.

Insert a Tooltip Widget

Locate the SpryTooltip.js file and add it to your web site. You can find the SpryTooltip.js file in the widgets/tooltip directory, located in the Spry directory that you downloaded from Adobe Labs.
Create a folder called SpryAssets in the root folder of your web site, and move the SpryTooltip.js file to it. The SpryTooltip.js file contains all of the information necessary for making the Tooltip widget interactive.
Locate the SpryTooltip.css file and add it to your web site. You might choose to add it to the main directory, a SpryAssets directory, or to a CSS directory if you have one.
Open the web page to add the Tooltip widget to and link the SpryTooltip.js file to the page by inserting the following script tag in the page's head tag:
```
<script src="SpryAssets/SpryTooltip.js" type="text/javascript"></script> 
```
Make sure that the file path to the SpryTooltip.js file is correct. This path varies depending on where you've placed the file in your web site.
Link the SpryTooltip.css file to your web page by inserting the following link tag in the page's head tag:
```
<link href="SpryAssets/SpryTooltip.css" rel="stylesheet" type="text/css" /> 
```
Make sure that the file path to the SpryTooltip.css file is correct. This path varies depending on where you've placed the file in your web site.
In the body of the page, add text and create a container tag. This will be the trigger area. Notice that the <span> has an ID="trigger".
```
<p>This will be the <span id="trigger">tooltip trigger</span>.</p>
```

Add the tooltip container and populate it with the tooltip content. This container will have an id="container".

<p>This will be the <span id="trigger">tooltip trigger</span>.</p>
<div id="container">This is the tooltip content</div>

Next we add the constructor script. It is important that this script tag be below the tooltip widget markup.
```
<p>This will be the <span id="trigger">tooltip trigger</span>.</p>
<div id="container">This is the tooltip content</div>
<script type="text/javascript">
var tt_one = new Spry.Widget.Tooltip("container","#trigger");
</script>
```
The arguments for the constructor are:
1. The ID of the tooltip container.
2. The CSS selector of the trigger. Notice that we have to put the # in front of this ID, to transform the ID in a CSS selector. The selector can specify an element ID, can be a class name, HTML tag name or a more complex selector as a combination of the these.
It's that easy. View the page in the browser and mouse over the trigger. The tooltip should show up.

You may want to make the trigger a link, so that people know that it does something. If so you can change the <span id="trigger"> to <a href="#" id="trigger"> and change the closing tag as well. Or because the tooltip isn't exactly a link, a CSS class can be defined that can denote a tooltip element, such as a different background color.

Tooltip Defaults and Options

There are a few options for the tooltip that will let you customize the behavior of the tooltip.

Option Name	Description	Default	Values
closeOnTooltipLeave	The content within the "tooltip" element may contain links or other interactive elements. Using this option will keep the "tooltip" element open even if the mouse leave the "trigger" element until the mouse leaves the "tooltip" element. If set to 'false', the "tooltip" element will close when the mouse exits from the "trigger" area. Note:It is recommended when enabling this option to also use the hideDelay option to allow the necessary time for the mouse to go over the "tooltip" element.	false	Boolean: true or false
followMouse	When set to "true", the "tooltip" element position will move along with the mouse movement inside the "trigger" element, using the specified offset values.	false	Boolean: true or false
showDelay	The delay in milliseconds for the tooltip element display after the mouseover event is received.	0	number in milliseconds
hideDelay	The delay in milliseconds for the tooltip element to hide after the mouseout event is received.	0	number in milliseconds
hoverClass	The specified class name will be appended to the 'class' attribute for the "trigger" element on mouse over to style differently a hovered "trigger" element. This value is removed when the "tooltip" element is hidden.	null	CSS class name
offsetX	The offset value given as an integer or in pixels for the x-axis. Using this value and the mouse entering position the widget compute the "tooltip" element horizontal position.	"20px"	string or number - X axis offset distance
offsetY	The offset value given as an integer or in pixels for the y-axis. Using this value and the mouse entering position the widget compute the "tooltip" element vertical position.	"20px"	string or number - Y axis offset distance
useEffect	The effect to be used when the "tooltip" is displayed or hidden. Could receive two parameters: 'blind' and 'fade'. Default value is none: useEffect:""	empty	"blind" or "fade"

Using Options

Options are set in the constructor, within curly braces {}. For example:

<script type="text/javascript">
var tt1 = new Spry.Widget.Tooltip("apDiv1", "#myDiv", {hideDelay:500, showDelay:200, hoverClass:"toolTipHover", useEffect:"blind", followMouse:true, offsetX:"30px", offsetY:20});
</script>

As with other Spry widgets, you may want to either generate the markup with Spry Data or populate the content with Spry Data. A common tooltip scenario is a variation of the master/detail pattern. As in our products demo, the table is the master element, and the detail region updates in response to the mouse click on the row. With the tooltip, we can make that detail region the tooltip and the row click the trigger. A working sample is here.

The key to working with Spry Data and the Tooltip Widget, much like other widgets, is that due to the asynchronous nature of Spry Data, you have to control the regeneration of the widget when the data updates. The simplest way to do this is with Observers. Using Observers, we regenerate the Tooltip widget every time the main region is updated. We use the onPostUpdate notification for this. The basic code looks like:

<div spry:region="ds1" id="mainRegion">
 <!-- Set the onMouseOver event to trigger the detail region update. The class name 'trigger' is used in the constructor. -->
 <div spry:repeat="ds1" onmouseover="ds1.setCurrentRow('{ds_RowID}');" class="trigger">{firstname} {lastname}<br /></div>
</div>
<!-- The tooltip container. The id is used in the constructor. -->
<p spry:detailregion="ds1" id="tooltip">Phone:{phone}<br />
 UserName:{username}<br />
 ID:{@id}</p>
 <!-- The Observer script. Add an observer to run the tooltip constructor after the detail region is loaded. 
'mainRegion' is the ID of the main region. onPostUpdate tells the function() to run after the new data is loaded. 
The actual widget constructor is the function in the observer. -->

<script type="text/javascript">
 Spry.Data.Region.addObserver('mainRegion',{onPostUpdate:function(){var tt1 = new Spry.Widget.Tooltip('tooltip','.trigger');}});
</script>

'mainRegion' is the ID of the Spry region we are listening to for data updates.
The class 'trigger' is used so we can attach one tooltip to multiple elements.
The ID 'tooltip' is the detailregion.
We use the onmouseover event to trigger the data set update with 'setCurrentRow'.