Advanced Tipmage Usage
This page provides a more verbose explaination of the basic usage of Tipmage, as well as in-depth directions on how to use Tipmage advanced features (such as callback functions, which can be used to perform AJaX calls).
Usage
First of all, it is necessary to include the .js and .css files in the page. There are different ways to do it: one of them is to include the following lines in the <head> section of the page.
<link rel="stylesheet" type="text/css" href="Tipmage-1.0.css" />
Somewhere in the page we will have the image. We need to give it a unique ID (like "mainImage").
Now we need to instance the Tipmage class: the parameters are the ID of the image we just set and whether the tooltips should be editable (true) or not (false).
After having instanced the class, we have to startup the Tipmage engine.
Now we can declare some tooltips. The parameters for the tooltips are horizontal and vertical position of the rectangle, width and height of the rectangle and the text to attach to the tooltip.
All of this should be enclosed in a <script> tag, as shown in the following example:
var tipmage = new Tipmage('mainImage',true);
tipmage.startup();
tipmage.setTooltip(150,80,40,30,'I have been up here!<br>No, just kidding... ;)');
tipmage.setTooltip(200,185,50,20,'Where is Wally?');
</script>
Advanced operations
Tipmage provides tools to create and edit tooltips, but they would be pretty useless without a way to give them persistence (for example saving them in a database). To gain persistence we will use callback functions.
Tipmage provides 3 function stubs: onInsert, onUpdate and onDelete. These functions will be called automatically by the engine with the right parameters, which are: ID of the tooltip, horizontal and vertical position of the rectangle, width and height of the rectangle and the text attached to the tooltip.
By implementing the stubs, we can make Tipmage do what we want with our data.
Let's see an example illustrating how to implement the onInsert function. This code should go in the same place as the code showed above.
tipmage.onInsert = function (identifier,posx,posy,width,height,text) {
// do something, like an AJaX call or whatever...
};
</script>
onInsert is called when a new tooltip is added, onUpdate is called when an existing tooltip is modified, onDelete is called when an existing tooltip is deleted.
Using identifiers
When new tooltips are added - using the setTooltip function, or in edit mode - a unique numeric identifier (ID) is assigned to them. This ID is the identifier parameter that will be passed to the 3 callback functions.
The ID is unique only for a certain image: this means that to uniquely identify tooltips belonging to different images (for example in a database), the pair tooltipID-imageID should be used.
The most tricky part of ID handling is to keep aligned the IDs in the database with the IDs used by Tipmage. In order to assign to a tooltip the same ID it has in the database, it is possibile to set an optional parameter in the setTooltip call. Here is an example:
tipmage.setTooltip(150,80,40,30,'I have been up here!<br>No, just kidding... ;)',1);
tipmage.setTooltip(200,185,50,20,'Where is Wally?',5);
</script>
The first tooltip's ID will be 1, while the second one's will be 5. Should we edit the second tooltip, Tipmage would automatically call the onUpdate function with the identifier parameter set at 5.