maTooltip 1.0.0

maTooltip uses the jQuery framework under the hood, so obviously you'll need that (yes, we're using our own local reference variable $ in the code). The style sheet maTooltip.css is where you poke around with the visual apperance. Besides the stylesheet, you can programmatically specify a per tooltip custom inline_style as a setting passed to the constructor. Most notably, you'll perhaps want to change the opacity rule as declared by selector .maTooltip in the style sheet or play around with the color values. The opacity rule should be there though as it will be parsed by the script once the site loads, else maTooltip will fall back to a hard coded value of 0.8 (programmatically changeable). The javascript code that reads this value will look for a linked style sheet with the attribute title set to maTooltip, or if that fails, he will have a case-insensitive look at the href attribute trying to find maTooltip.css. You will need maTooltip.js or maTooltip.min.js which will give you the almighty maTooltip object (namespace and constructor). The constructor shall create new tooltips for you (there is also a factory method: maTooltip.quickTooltip).

You'll find all files to download and other resources (such as an explanation for the presence of two "different" .js files) over at the Download page.

Constructor and usage

The constructor accepts as his first argument, a target_element which will serve as the anchor for the position of a tooltip (the position on screen is calculated, all based on the position of the target element. However, the tooltiper's parent node will become the body element's first child. This placement fix a bugg in the Opera browser and are furthermore configurable). Second argument to the constructor is a map object with settings. Most noteworthy is a setting called static_message. This setting's value shall be a string with the message to display in the tooltip. The message can be set in plain text or HTML that jQuery will parse for you. The message can also be an object or a function (see Basic example 3 and Basic example 4). The tooltiper won't show until you call .show (the factory method maTooltip.quickTooltip makes that call for you, see here for an example). This method can optionally recieve as an argument, a message to display for this one particular occurance. If you don't pass along this argument with your call, and for all consecutive calls made to .show without an argument supplied, the tooltip will revert to the static_message supplied upon creation. The tooltip will hide himself if notfull_visibility_duration has been set to -1 (infinity) in the settings object sent to the constructor. Otherwise, you will have to call .hide on your own. And if you do, you can optionally pass in true as an argument. That will make the tooltiper immediately hide himself without any regard to current animations set. You can toggle the current visibility state with .toggle.

Using the constructor is the prefered way. Whenever you are completely done with a tooltip and you are keen to save every byte of memory, make a call to .dispose. Read more about it in the next example.

Clicking on the button in this example will create one new tooltip on each click. The factory method is a conventient way to say something to your visitors fast and only once. Normally, there will always be one reference to each tooltip stored in maTooltip.INSTANCES. The one exception is when you use the factory method or manually set the option one_time_only to true (read more about this setting on the API reference page). And once this tooltiper is hidden, he is completely removed from the DOM and not just detached. These procedures promote garbage collection effectiveness. Even though the factory method actually returns a reference to the new object, the reference should be used sparingly – if at all.

Whenever you want to have a particular context for your object, you should use .bind in ECMAscript 5, jQuery.proxy, or even try to fall back to .call and .apply in ECMAscript 3. If you send an object as a message to .show, he will call this object's .toString method. Thus you can overload your object's .toString() method however you want.

By default, when you call .show and the message changed since the last time a tooltiper was visible, and the tooltiper currently is visible, then the tooltiper will immediately hide himself first and then make a consequtive call to .show. This will produce a flash effect and the purpose is to promote attention from the website visitor. If we disable this effect by setting the value of the default setting flash_on_text_change to false, then the tooltiper will do what he would do if the message never changed from the first place, which is to "only" prolong the visibility duration. Also, long messages might not always look good with the max-width: 200px rule set by the style sheet. This example overcomes both. You should note that in this example, we change the default behaviour of the flash for all global tooltiper's (currently, there is no way to do this on an individual level). You can equally as much set animations, visibility duration and the like on a global level too by programmatically change the corresponding default values like we do here for the flash.

Behind the scenes, your message are passed to jQuery's .html method, so you can play around with HTML code in your message all you want too. But there's another way for creativity too. Every tooltip saves three jQuery handle's to his created DOM elements which you can get and thereafter do something something with. They are all div elements stored as .DOM.$divParent, .DOM.$divArrow and .DOM.$divContents. The $divParent is a wrapper div for the other two. $divArrow is the arrow you see always pointing towards the target element, also known in this business as a "stem". $divContents holds all the contents. In this example, we hide the arrow and grab a hold of the content div to programmatically change his contents and appearance. By default, full_visibility_duration is set to -2 which makes an internal algorithm compute time to live whenever our content changes. One major factor in this computation is the amount of plain text words in the tooltipers contents. In this example, we only use two words and the computed value feels a little bit low given that we've added some nice graphics for the user to look at. Therefor, we shall double the alghoritm's result by supplying calculated_time_offset = *=2.

There is no native support for callbacks, it doesn't fit the design scheme of maTooltip. If you feel that you have a valid reason or two, send me a mail and I will think about it. A power user can mimic these features with the help of variables stored in every tooltip. Here's one example.

The setting move_in_from must be an object that specifies custom coordinates via its properties .top and .left (numeric values). Here's an example that should also show you that whenever you're animating a tree of elements (such as a maTooltip), you should never do animations over long periods of time and certainly not move animations over long distances. The internal relationship of properties between the elements will not render flawless. Also, if you actually click on the toggle button below to preview the result, some browsers might not have read the offset correctly because in theory, the target element might not have any coordinates just yet. The live demo below is keept in an <iframe> tag that most likely didn't have a size when his document loaded. If you experience any troubles here, take a look at the example in a new window/tab instead. I've also included example code as a comment that could be used in this particular case to solve our problem. However, there should almost always never be a reason for you to not parse offset and the like after the document has finished loading. It isn't a concern for you unless you explicitly set custom coordinates as in this case. Internally, maTooltip setup proper handles accordingly (actually, the only handle registered during the life time of a webpage is one that repositions dislocated tooltipers when the window is resized) and whenever he needs to deal with the offset of a target element, then this stuff will get reexamined everytime .show is called.

You should have fully read and understood the last example before trying this one. Here we'll do pritty much the same, but also specify a custom coordinate for the final position of the move-in animation. To the rescue is an option called move_in_to that accepts an object with properties .left and .top set to numeric values. Thus if we supply this option to the constructor, the position setting will not have a saying about where the tooltiper is finally placed. position still dictates were the stem will be located on the tooltip. In this example, we'll just hide it completely. Like in the last example, you can click here to open the demo in a new window or tab.