# tipsy - Facebook-style tooltip plugin for jQuery

## Overview

Tipsy is a jQuery plugin for creating a Facebook-like tooltips effect based on an anchor tag's title attribute.

## Examples & Usage

### Basic

By default, tooltips will appear centred underneath their anchor:

Hover over me

Basic example:

    $('#example-1').tipsy();

### Gravities

Using the gravity parameter, it's possible to control the positioning of the tooltip relative to the pointee:

North | South
East | West

Gravity example:

    $('#foo').tipsy({gravity: 'n'}); // n | s | e | w

As of version 0.1.3, it's possible to use a callback function to set the gravity dynamically at hover-time. Within the callback, `this` refers to the active element, and the function should return the calculated gravity as a string. Two demo callbacks are supplied - `$.fn.tipsy.autoNS` and `$.fn.tipsy.autoWE` - which select north/south and west/east gravity, respectively, based on the element's location in the viewport.

Here's an example (scroll the page to see the effect):

Dynamic Gravity
Dynamic gravity example:

    $('#foo').tipsy({gravity: $.fn.tipsy.autoNS});

### Fading

For full Wob2.0 compliance, you must fade these badboys in:

Hover over me

Fade example:

    $('#example-fade').tipsy({fade: true});

### Bonus Feature

You can EVEN COMBINE FADE AND GRAVITY! (exercise for reader)

### Slightly Advanced Usage

Tooltip text can be set based on any attribute, not just `title`:

Hover over me

Custom attribute example:

    $('#example-custom-attribute').tipsy({title: 'id'});

If any attribute isn't good enough, you may pass a callback function instead. It should return the tooltip text for `this` element:

Hover over me

Callback example:

    $('#example-callback').tipsy({title: function() { return this.getAttribute('original-title').toUpperCase(); } });

Finally, it is possible to specify a fallback tooltip for any element which does not have any tooltip text:

Hover over me

Fallback example:

    $('#example-fallback').tipsy({fallback: "Where's my tooltip yo'?" });

If your tooltip content contains HTML, set the `html` option to `true` (relies on invalid HTML, sorry):

Hover over me

HTML example:

    $('#example-html').tipsy({html: true });

## Notes

Tipsy needs to erase any existing value for an element's `title` attribute in order to suppress the browser's native tooltips. It is stashed in the element's `original-title` attribute in case you need to retrieve it later.

As of version 0.1.4, the tooltip text is recomputed on every hover event so updating the `title` attribute will have the expected effect.

## Download

### Package

Package downloads are available from the jQuery project page.

### github

    jason@donut ~ $ git clone git://github.com/jaz303/tipsy.git