What is tipy! ?

tipy! is just a jQuery tooltip plugin, nothing more, nothing less. You hover,a tooltip is shown. That's all!

So, What's so special about it?

Lots of things actually! Here is a list:

It's basic functionality is extremely simple.
1. Include The tipy.js and tipy.css files.
2. Add the desired text in a data-tipy attribute on your desired element(s).
3. Done!
It is based on Event Delegation, which, in plain words, means that you don't have to set-up every single tipy! on the screen. In fact, you won't have to do anything even if a tipy-element jumps into your page, e.g. form an ajax call, a DOM manipulation, or even if you put one yourself.
It can also work with titles ( or any other attribute ) with just a minor change.
It never gets out of the screen ( unless the screen is smaller than the tooltip... ).
It is just one element!

Ok but... Can I trigger it manually?

Of course you can! It is supposed to be a jQuery plugin isn't it?

Just use it like this

$('.your-element').tipy("Your tipy! Text!");

Your tipy! will pop up, it will calculate the time needed for the tooltip to be read and it will vanish as soon as this time has passed.

Cool! What about the custom styles?

*ahem* Actually... There are no custom styles...

That's Ridiculous! Why?

Custom styles are never -really- custom, they are just 'predefined styles'. Predefined design cannot suit everyone unless it is really REALLY generic. And then again, someone will always have to dive into the CSS to do some slight changes. That is the main reason I skipped this step, after all, almost everyone knows how to write a couple lines of CSS ( and unfortunately, almost everyone has to in the end ).
Sounds like a silly concept, but here's the math behind it:

x predefined styles -> x possibilities
0 predefined styles -> infinite possibilities!

So... Dive in and make your own awesome styles.

Create my own Styles?

Yep! And it's not that hard! As I said before, it is just one element, plus, the default style sheet is pretty well commented, I believe it'll help you get started.

Ok! I'm convinced! How much?

tipy! is ( and will forever be ) free.

Nice! Where can I get it?

You can get it [here] (.js and .css file). Or you can go to the project on GitHub https://github.com/xpy/tipy.

In Detail...

What can tipy! do?

It can be used like a common 'hover tooltip'
It can be manually triggered
Manual trigger can be done with options ( position, duration, additional Classes )
It has an automatic duration calculator depending on the tooltips words
It has an automatic positioning calculator, optionally depended on user defined positions
It works with titles as well
It will vanish if the trigger-element leaves the DOM

What does tipy! not do?

You cannot have more than one tipy! on-screen at a time
It does not have "display options"
It doesn't do Ajax ( yet )
It doesn't adapt on window resize

Usage

First of all you should include the tipy.js and tipy.css files:

<script src="js/tipy.js"></script>
<link href="css/tipy.css">

This will set up the tipy! with the default hover functionality. Which means that every element with a data-tipy attribute will display a popup on hover with the data-tipy attribute value as content.

If you want to use another attribute instead of data-tipy, you can use

tipyController.setAttr("YourAttr");

for run time use, or alternatively you can edit the tipyController function in the tipy.js file,there are comments to show you the way. If you want to disable the default hover behaviour you can do it by calling

tipyController.disable();

Then you can enable it again with

tipyController.enable();

Manual Trigger

You can trigger a tipy! manually the same way you will use any jQuery plugin

$('.tipy-element').tipy();

The tipy() function typically takes four arguments:

The tipy! text ( as string )

The desired positioning ( as a string )

The duration of the tipy! ( as an integer, in ms )

Any additional classes to be added to the tipy! ( as a space separated string )

Example:

$('.target-element').tipy('tipy!','top',5000,'red shaky');

This one will display a tooltip with the content 'tipy!' on top of the "target-element" which will stay for 5secs and will have the classes red and shaky.

The function can also be called with less or even zero arguments. Bellow are all the possible variations:

$('.target-element').tipy('tipy!','top',5000);

Omitting the last ( class ) argument will add no classes to the tipy! element

$('.target-element').tipy('tipy!','top');

Omitting the last ( class ) and before-last ( delay ) argument will force the tipy! plugin to calculate the delay based on the time needed to be read.

$('.target-element').tipy('tipy!','top','red');

You can also omit the delay argument by passing a string, which will then be passed as the class argument

$('.target-element').tipy('tipy!');

Omitting the last three arguments will result in a tipy that will calculate the delay and also display in the first available space around the target, starting from top and going clockwise

$('.target-element').tipy();

Omitting all the arguments, tipy! will try to get it's content form the data-tipy attribute, if there is no such attribute, it will try the title attribute. The Position and the Delay will be automatically calculated

$('.target-element').tipy(5000);

Passing an int as the first argument, content and position will be automatically calculated

$('.target-element').tipy(5000,'red');

You can as well pass a class after the delay.

$('.target-element').tipy(null,'top',5000,'red');

You can pass 'null' as the first argument if you want only the content to be automatically calculated

Positioning, Delay and Classes

Positioning can be done using the words below as a comma separated string:

top ( or t )

tr ( for top-right )

right ( or r )

br ( for bottom-right )

bottom ( or b )

bl ( for bottom-left )

left ( or l )

tl ( for top-left )

example:

$('.target-element').tipy(null,'top,right,bottom,left',5000,'red');
$('.target-element').tipy(null,'t,tr,r,br,b',5000,'red');

There are also some predefined keywords:

all ( behaves like 't,tr,r,br,b,bl,l,tl' )

cross ( behaves like 't,r,b,l' )

x ( behaves like 'tr,br,bl,tl' )

hor ( behaves like 'r,l' )

ver ( behaves like 't,b' )

tipy! will be displayed in the first position with the available visible space. If there is no such position ( e.g. it is out of view ) it will be displayed on top

If no delay is defined ( e.g. the delay is not a number ) the delay will be calculated by the number of the content's words, this may not be very accurate but it's pretty useful if you don't want to define a delay for every tipy but you really need to have one. Also, if the delay is less or equal to 0 the tipy! will be a "sticky" one and will vanish only if the user clicks on it. The tipy! will leave on click even if it is on a delay.

At this time, there are three extra classes defined in the css file and they exist mostly for demonstrating purposes. More may be added in the future. Here they are:

red ( makes the background of the tipy red )

yellow ( makes the background of the tipy yellow )

shaky ( makes the tipy shake a short time after it pops up )

That's all you need to know about the tipy!