1. Introduction
The Uize.Widget.AutoTooltip class makes it easy to display fancy / decorated HTML tooltips for nodes, using data that is tucked into their attributes.
DEVELOPERS: Chris van Rensburg
The Uize.Widget.AutoTooltip module defines the Uize.Widget.AutoTooltip widget class, a subclass of Uize.Widget. Using this module, one can achieve easy, wizard style augmentation of a large number of nodes, with an "Unobtrusive JavaScript" approach that provides graceful degradation in the event that JavaScript is disabled, the JavaScript fails, or the wiring up of the behavior takes a long time.
This module supports displaying of an HTML tooltip when mousing over each node in a specified array of nodes, where the HTML for the tooltip is automatically generated from data harvested from the title, alt, or other attribute of the nodes. The HTML template for the decorated tooltip is specified in the html set-get property of the instance, where the value can be a function that accepts the tooltip data as its input parameter and returns a string value that is the generated HTML.
2. Set-get Properties
2.1. data
An object, representing the tooltip data for the current node being moused over.
NOTES
the initial value is undefined | |
| the value of this set-get property is set automatically | |
when the mouse is not over one of the nodes specified in the nodes set-get property, then this property will have the value null or undefined | |
see also the dataAttribute and dataDecoder set-get properties |
2.2. dataAttribute
A string, specifying the name of the node attribute that should be used for obtaining the tooltip data.
When this set-get property is set to the special value 'auto', then the instance will try to use the title attribute. If no value is set for the title attribute, then the instance will fall back on using the alt attribute. If you wish to explicitly force use of either the title or alt attribute, then specify the desired one as the value for the dataAttribute set-get property. If the data is stored in a custom attribute (eg. tooltipData), then simply specify that custom attribute's name.
NOTES
the initial value is 'auto' | |
see also the dataDecoder set-get property |
2.3. dataDecoder
A function, being the code that will be used to decode the value of the data attribute (specified by the dataAttribute set-get property) for all the tooltip nodes, to produce an object hash containing key/value pairs.
The function specified by this property should expect a single string parameter and should return an object hash containing key/value pairs.
The initial value is a function that decodes strings of the form...
KEY NAME 1: value 1 | KEY NAME 2: value 2 | KEY NAME N: value N
...to produce objects of the form...
{
keyName1:'value 1',
keyName2:'value 2',
keyNameN:'value N'
}
The default data decoder requires key names to be in all caps, and key/value pairs to be separated by the "|" (pipe) character. Key names are converted to camelCase, with the first letter of all words after the first word capitalized. Spaces around key names, value names, and the pipe separator are non-significant and are collapsed. This encoding/decoding scheme allows for the tooltip text to be as pretty/readable as possible for the sake of graceful degradation.
EXAMPLE
In the event that the tooltip data was encoded in JSON format, then you could specify a JSON decoder as follows...
myInstance.set ({dataDecoder:Uize.Json.from});
NOTES
see also the dataAttribute set-get property |
2.4. nodes
An array, representing the nodes that should be wired up to display an automatically generated tooltip when mousing over them.
To easily set a value for this property, a method such as the Uize.Node.find static method may be used to find nodes in the document.
NOTES
the initial value is undefined |