sgTooltip.js
Reference Manual
[return to top]
Introduction
This is the manual for sgTooltip.js, a Javascript library that aims to provide a simple but flexible way to produce tooltips without needing to write any Javascript yourself.
This document serves as a reference manual for sgTooltip.js, and as such may not be the best place to learn from immediately, if this is your first encounter with sgTooltip.js, I recommend that you look at the examples pages first.
[return to top]
Getting Started
[return to top]
Download
The first step to using sgTooltip.js is to download it, the permanent download location for the stable version can be found at:
If you need other versions, please visit the download page.
[return to top]
Extraction
Once you've downloaded the file extract it, using:
tar -xzf sgTooltip-stable.tar.gz
You will be left with a directory called something like sgTooltip-1.0.1.1, depending on the version you downloaded. Within that directory will be the sgTooltip.js file.
[return to top]
Prototype.js
sgTooltip.js makes use of the the Prototype Javascript Framework, you will need to have version 1.6.0.2 or later installed, or visit their site to download and install it.
[return to top]
Using sgTooltip.js
[return to top]
Terminology
Here's a list of terms used within this documentation that it may help to understand:
Hotspot
A hotspot is an area of a web page that causes one or more tooltips to display when the mouse moves over the hotspot.
In terms of sgTooltip.js, any DOM element that produces mouse events may be used as a hotspot.
Tooltip
A tooltip is an item to display in response to a hotspot activating. Usually it contains some form of context-dependent information relating to the active hotspot.
In terms of sgTooltip.js, any element within the page may be designated as a tooltip.
[return to top]
Loading the Javascript
In order to use sgTooltip.js, you will need to load the Javascript within your page. The easiest way to do this is via the <script> tag within the <head> section of your page:
<script type="text/javascript" src="/path/to/your/javascript/sgTooltip.js">
</script>
You should be sure to do this after you have loaded prototype.js, otherwise you'll get a whole spam of errors.
If you prefer to defer your non-core Javascript loading to reduce delay for the page to appear to have finished loading, you can do that too, sgTooltip.js copes equally well with waiting for the DOM to finish loading or with being the johnny-come-lately itself.
[return to top]
Namespace Definition
In order for your page to validate as correct XHTML1.0, you need to add the sgtooltip namespace to your document, this is a trivial addition to your <html> tag:
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"
xmlns:sgtooltip="http://www.illusori.co.uk/xmlns/sgtooltip/">
This tells the browser or validator that the sgtooltip namespace is a valid namespace for new attributes.
[return to top]
Adding a Hotspot
Once you've got sgTooltip.js loading in your page, you'll probably want to use it, to do this you'll first need to set up a hotspot and then some tooltips.
Adding a hotspot is trivial, you mark any element as being a hotspot by giving it the CSS class tooltip-hotspot, this can be in addition to any other CSS classes that the element has.
Here's an example with a <div> tag:
<div class="my-normal-css-class tooltip-hotspot">
This is a hotspot.
</div>
Easy yes? Of course a hotspot isn't much good on its own, you need to indicate what tooltips it should activate too. You do this with the sgtooltip:tooltip attribute on the hotspot, so our above example should really be:
<div class="my-normal-css-class tooltip-hotspot"
sgtooltip:tooltip="my-tooltip-id">
This is a hotspot.
</div>
In the example this will activate the hotspot with id my-tooltip-id. You can supply more than one tooltip by providing a space-seperated list, in the order that you wish them to be stacked.
[return to top]
Adding a Tooltip
Now that you've added a hotspot, you'll want to add a tooltip. Well the good news is that this is the easiest bit. You don't need to do anything special, other than create an element that has the id that you used in your hotspots.
No, really, that's it. You can use anything you like as a tooltip, you just refer to it by id in the hotspot's sgtooltip:tooltip attribute.
You'll probably want start simple by using a plain <div> with some text in it, and you'll probably want to hide the tooltip away in a containing div that has been styled to be hidden:
<div style="display:none;">
<div id="my-tooltip-id">
This is a tooltip!
</div>
<div id="my-second-tooltip-id">
This is a second tooltip!
</div>
</div>
[return to top]
Hotspots Reference
[return to top]
position
You can define which tooltip stack the tooltips from a hotspot will appear in with the sgtooltip:position attribute.
Valid values are mouse-relative (the default), element-relative and fixed.
[return to top]
stacking
You can define the stacking behaviour of multiple tooltips activated by a hotspot using the sgtooltip:stacking attribute.
Value values are vertical (the default), horizontal and stacked.
[return to top]
flipX, flipY
You can control the behavior of the tooltip layout when a tooltip would overflow the edge of the screen with the sgtooltip:flipX and sgtooltip:flipY attributes.
Valid values are true and false, by default flipX is true and flipY is false.
If an axis is set to flip then when the tooltip reaches the edge of the screen in that direction, it will flip in its entirity to the other side of the anchor location, whereas if the axis is set to false it will merely slide enough to ensure that it doesn't flow off the screen.
For mouse-relative tooltips you will almost certainly want to set one of these attributes to true (the default does this for you by setting flipX to true), otherwise hotspots near the corners of the display area will run the risk of sliding under the mouse pointer and obsuring what the user is trying to mouse-over.
[return to top]
suppressTitle
Not currently implemented.
This will suppress the native browser display of the title attribute of the hotspot in a tooltip, since two tooltips (probably of slightly different styles) would be confusing.
[return to top]
Hotspot Stacks Reference
[return to top]
Styles
The three layout divs that form each tooltip stack are given the CSS classes sgtooltip-float, sgtooltip-stack and sgtooltip-container respectively.
It is recommended that you do not directly style these classes, however they can be used in CSS selectors for rules:
.sgtooltip-container img { border: thick blue solid; }
This would cause all images within tooltips to have thick blue solid borders. You maybe could have done this directly in a class used by the tooltip itself, but sometimes that may not be an option.
[return to top]
sgTooltip Object Reference
[return to top]
sgTooltip.Version property
The sgTooltip.Version property holds a string representation of which version of sgTooltip.js is being used, it will take the form '1.0.0.1'.
Please note that the V of Version is capitalized.
[return to top]
sgTooltip.tooltipStacks property
The sgTooltip.tooltipStacks property is an object with properties named after each tooltip stack position with a value of the relevent tooltip stack itself.
[return to top]
scanForTooltips()
The sgTooltip.scanForTooltips() method is called when the DOM has finished loading, and scans the document for any tooltip hotspots.
If for some reason you wish to cause a scan to happen again, you can trigger it by calling sgTooltip.scanForTooltips() manually. An example of why you may wish to call this would be if an AJAX response has updated the DOM with new elements that may be hotspots.
[return to top]
removeAllTooltips()
The sgTooltip.removeAllTooltips() method will remove and deactivate all tooltip hotspots, if you want hotspots to start working again, you will need to call sgTooltip.scanForTooltips() manually.
[return to top]
Known Issues and Bugs
Original tooltip order not preserved
When tooltips stop displaying as a tooltip and are moved back to their original place in the document, their order within the children of their original parentNode isn't preserved.
You can see a demonstation of this within example two of the examples page, if you activate the first hotspot then leave the hotspot, the first tooltip will appear back in the right-hand column at the end of the list.
This behaviour is technically a bug, however there are several simple workarounds, for example: you can place each tooltip in a containing <div> with only the single child, that div will then hold the tooltip's position.
Considering the ease of the workaround, and the fact that in most normal use your inactive tooltips will be hidden, this isn't considered a high priority bug to fix.
Horizontal stacking doesn't working IE
Currently the 'horizontal' stacking option behaves identically to 'vertical' in IE.
[return to top]
Intentionally Missing Features
There are a number of features that other tooltip libraries provide that have been intentionally left out of sgTooltip.js. sgTooltip.js doesn't set out to be a "does everything" library, it's intended to mostly do one thing and do it well, if any feature would interfere in its ability to perform as well as it can, then that feature will not be added.
Some examples of things that won't be added:
Tooltip delays
Messing around with delays rather than instantaneously displaying in response to mouse movements is a pain and added complexity and a lot of places for strange bugs to creep in. Unless I personally find a sudden need to use it, or someone presents me with a rock-solid patch and is willing to maintain it, then I'm not going near this with the proverbial 50-foot barge pole.
Tooltip fadeouts
See above comments about tooltip delays, the whole "reacts immediately to state changes" thing makes my life a whole lot more pleasant.