clueTip : A jQuery Plugin

This is a demo page for the new clueTip — a jQuery-based, AJAX-powered tooltip developed by Karl Swedberg.

Read the blog entries for Beta 1 and Beta 2 for more information and examples.

This version (0.8.x) includes some fairly major API changes, so if you're upgrading from a previous version, be sure to check out the inline documentation.

Credits

The clueTip plug-in was inspired by Cody Lindley's jTip script.
Many feature ideas were provided by Shelane Enos.
Glen Lipka, Dan G. Switzer, and Jörn Zaefferer provided expert advice.
Torben Schreiter helped squash some bugs and offered code for pre-loading images from ajaxed files
Jonathan Chaffer helped a lot, but eschewed the co-author designation out of sheer modesty.

If you like this plugin and you're feeling generous, perhaps you'd also like to visit my amazon.com wish list?

Features

The clueTip plug-in allows you to easily set a link to show a "tooltip" of sorts when the user's mouse hovers over the link. If the link includes a title attribute, its text becomes the heading of the clueTip.

Multiple Content Sources

The contents of the clueTip can come from one of these sources:

a separate file, via AJAX
an element on the same page, typically hidden
the title attribute, parsed by a user-defined delimiter (if the "splitTitle" option is set). The text before the first delimiter becomes the clueTip title, and the rest of the text parts are placed in <div class="split-body"></div> elements and appended to the clueTip body

Smart Positioning

uses the excellent Dimensions Plugin for all of its positioning needs
switches from the right side of the link to the left side, if there is not enough room between the link and the right edge of the browser window
moves up until the whole clueTip is visible, if the link is too close to the bottom edge of the browser window.
moves back down until the clueTip's top is at the top edge of the browser window, if the clueTip is taller than the window (the viewable area)
sits to the right or left of the mouse position, if the link is a block-level element or if the link is so wide that the clueTip can't completely fit to the left or the right of it.
drops below the mouse position, if the clueTip itself can't fit to the right or left of the mouse position. Moves above the mouse position only if (a) there isn't enough room below without being cut off, and (b) there is enough room between the top of the viewable area and the mouse.

Flexible Behavior

The clueTip takes advantage of Brian Cherne's fantastic hoverIntent plugin if it's available. (Just include it in a <script> tag if you want the clueTip to use it.)
It can be activated on hover or on click.
It can fade in, slide down, etc.
It can close when the link element is moused out or when the clueTip is moused out or when the user clicks the close link.
It can cache the results of ajax requests—or not.

Many, Many Options

Here is a list of the available. None of these are required.

width: default is 275
local: default is false; set to true to use an element on the current page for the contents of the clueTip.
hideLocal: default is true. If the local option is set to true, this one determines whether local content to be shown in clueTip should be hidden at its original location.
attribute: default is 'rel'; set it to some other attribute of the link to designate that attribute as the one that refers to the clueTip's content
titleAttribute: default is 'title'; set it to another attribute to use its text for the clueTip's title
splitTitle: default is an empty string; set to a character such as "|" to split the title attribute of a link into the clueTip heading (the first string, before the first delimiter character) and individual clueTip body divs (subsequent strings).
showtitle: default is true. Shows the title bar of the clueTip, whether a title attribute has been set or not. Change this to false to hide the title bar.
cluetipClass: default is 'default'; this adds a class to the outermost clueTip div with a class name in the form of 'cluetip-' + clueTipClass. It also adds "clue-left-default" or "clue-right-default" to the same div, depending on whether the clueTip is to the left or to the right of the link element. This allows you to create your own clueTip theme in a separate CSS file or use one of the three pre-packaged themes: default, jtip, or rounded.
hoverClass: default is an empty string; set to the name of the class to add that class to the link on hover
closePosition: default is 'top'; set to 'bottom' to put the 'close' link at the bottom of the clueTip. Additional formatting can be applied to a#cluetip-close in the style sheet.
closeText: default is 'Close'; set it to something else if you want to
truncate: default is 0, which means there will be no truncation; set it to some number to truncate the clueTip's contents to n characters
waitImage: default is true; Determines whether the wait image will be shown while ajax clueTips are being loaded. Set to false to avoid showing the image
arrows: default is false; set it to true to calculate the positioning of the clueTip's background images for .clue-right-[theme] and .clue-left-[theme] (where [theme] represents the cluetipClass indicated in the options).
dropShadow: default is true; set it to false if you do not want the drop-shadow effect on the clueTip
dropShadowSteps: default is 6; change this number to adjust the size of the drop shadow
sticky: default is false; set to true if you want the clueTip to remain open when you "mouse out" of the link. This option also places a "close" link on the clueTip itself.
cluezIndex: default is 97; sets the z-index style property of the clueTip.
positionBy: default is 'auto'. Available options: 'mouse', or 'bottomTop'. Change to 'mouse' if you want to override positioning by element and position the clueTip based on where the mouse is instead. Change to 'bottomTop' if you want positioning to begin below the mouse when there is room or above if not -- rather than right or left of the elemnent and flush with element's top.
fx: default is:
```
{
  open: 'show', 
  openSpeed: '', 
  close: 'hide', 
  closeSpeed: ''
}
```
change these to apply one of jQuery's effects when opening or closing the clueTip
activation: default is 'hover'; set to 'toggle' to force the user to click the element in order to activate the clueTip.
hoverIntent: default is
```
{
  sensitivity: 3, 
  interval: 50, 
  timeout: 0
}
```
If jquery.hoverintent.js plugin is included in the <head>, hoverIntent() will be used with these settings instead of hover(). Set to false if for some reason you have the hoverintent plugin included but don't want to use it. For info on hoverIntent options, see http://cherne.net/brian/resources/jquery.hoverIntent.html
onShow: default is function (ct, c){} ; allows you to pass in your own function once the clueTip has shown.
ajaxCache: default is true; caches the results of the ajax request to avoid unnecessary hits to the server. When set to false, the script will make an ajax request every time the clueTip is shown, which allows for dynamic content to be loaded.
ajaxProcess: default is:
```
function(data) {data = $(data).not('style, meta, link, script, title');
  return data;
}
```
This default value strips out tags from the <head> of an HTML page that is being pulled into a clueTip via "AHAH."
ajaxSettings: default is {dataType: 'html'}. You can change the value of the dataType argument or set other arguments that $.ajax() uses: async, contentType, timeout, type, etc. These arguments can't be used, because they're already being used by the plugin: beforeSend, complete, error, success, url. I might in a future version try to allow for passing in custom stuff for these arguments.

$.cluetip.setup()

Additionally there is a new $.cluetip.setup() method for setting global defaults applied to all clueTips. The options for this method are insertionType and insertionElement.

insertionType: determines the method to be used for inserting the clueTip into the DOM. Permitted values are 'appendTo', 'prependTo', 'insertBefore', and 'insertAfter'. Default is 'appendTo'.

insertionElement: Determines where in the DOM the clueTip will be inserted. Default is 'body'.

Setup

To use the plug-in, you'll need to include 4 JavaScript files in your web page's <head>, like so:

    <script src="scripts/jquery.js" type="text/javascript"></script>
    <script src="scripts/jquery.dimensions.js" type="text/javascript"></script>
    <script src="scripts/jquery.cluetip.js" type="text/javascript"></script>
    <script src="scripts/your-custom-file.js" type="text/javascript"></script>

As you can see, the clueTip depends on jquery.js and jquery.dimensions.js to function properly.

You should also include the stylesheet:

  <link rel="stylesheet" href="jquery.cluetip.css" type="text/css" />

If you would like to use clueTip in conjunction with the hoverIntent plugin, you will need to reference that plugin as well.

Link Prep

When you want to add a clueTip to a link, type the content's location in an attribute:

   <a href="foo.htm" rel="bar.htm">Link to foo.htm; show bar.htm in the clueTip</a>

The rel attribute is used by default, but you can change it to any other attribute you wish, like so: $('a').cluetip({attribute: 'name'}). Now you can write the HTML like this:

   <a href="foo.htm" name="bar.htm">Link to foo.htm; show bar.htm in the clueTip</a>

The href attribute is used for the actual link. If the rel (or your custom) attribute is the same as the href attribute, hovering over the link will turn the cursor into a question mark. Also, the link will become "dead," meaning that nothing will happen if the user clicks it:

   <a href="foo.htm" rel="foo.htm">Clicking me will get you nowhere</a>

Otherwise, clicking on the link will take the user to the URL in the href, as expected.

Examples

Here are some examples of how you can add a clueTip to your page:

Default Style

basic, no title attribute: This is the simplest example there is.
View the HTML
```
<a class="basic" href="ajax.htm" rel="ajax.htm">
```
View the jQuery
```
$('a.basic').cluetip();
```
custom width and hidden title bar: This tip has a custom width of 200px. The clueTip title bar is hidden. Try me!
View the HTML
```
<a class="custom-width" href="ajax3.htm" rel="ajax3.htm">
```
View the jQuery
```
$('a.custom-width').cluetip({width: '200px', showTitle: false});
```
non-link element, custom attribute, and hover class: Block-level items such as this h4 have clueTips positioned by the mouse.
Hover over me.

View the HTML
```
<h4 title="Fancy Title!" id="ajax3.htm">Hover over me</h4>
```
View the jQuery
```
$('h4').cluetip({attribute: 'id', hoverClass: 'highlight'});
```
sticky:This is a sticky clueTip with "close" text in the title bar: It won't close until you close it. Or until you hover over another clue-tipped link.
View the HTML
```
<a id="sticky" href="ajax6.htm" rel="ajax6.htm">
```
View the jQuery
```
$('#sticky').cluetip({sticky: true, closePosition: 'title'});
```

local: This one uses local content from a hidden div element: hover for local

View the HTML

<a class="load-local" href="#loadme" rel="#loadme">

View the jQuery

$('a.load-local').cluetip({local:true, cursor: 'pointer'});

sticky, truncated clueTip with custom hover class, close position, and close text (it also has a title). Its href is different from its rel, so if you click it, you'll go to the linked page hover for cluetip, click to visit URL

View the HTML

<a href="http://www.learningjquery.com" title="about this link:" rel="ajax6.htm">

View the jQuery

$('#examples a:eq(4)').cluetip({
  hoverClass: 'highlight',
  sticky: true,
  closePosition: 'bottom',
  closeText: '<img src="styles/cross.png" alt="" />'
  truncate: 60
});

click to activate: This one won't show the clueTip unless you click it: click me. It's also really wide.
View the HTML
```
<a href="ajaxclick.htm" rel="ajax5.htm" title="active ingredients">
```
View the jQuery
```
$('#clickme').cluetip({activation: 'click', width: 650});
```

jTip Theme

jTip Style clueTip, with slideDown effect and an image placed in the title for closing it, because it's sticky.
New: The clueTip will close if you mouse out of it.

View the HTML

<a class="jt" href="ajax6.htm" rel="ajax6.htm" title="jTip Style!">

View the jQuery

$('a.jt:eq(0)').cluetip({
  cluetipClass: 'jtip', 
  arrows: true, 
  dropShadow: false,
  hoverIntent: false,
  sticky: true,
  mouseOutClose: true,
  closePosition: 'title',
  closeText: '<img src="cross.png" alt="close" />'
});

This one has hoverIntent turned off. Look for the link floated right: jTip Style clueTip

View the HTML

<a class="jt" href="ajax5.htm" rel="ajax5.htm">

View the jQuery

$('a.jt:eq(1)').cluetip({cluetipClass: 'jtip', arrows: true, dropShadow: false, hoverIntent: false});

This one pulls the clueTip contents directly from the title attribute of a span tag: splitTitle clueTip
View the HTML
<span title="Split Title|This clueTip's contents were created directly from the title attribute|Nice for minimum info.">
View the jQuery
```
$('span[@title]').css({borderBottom: '1px solid #900'}).cluetip({
  splitTitle: '|', 
  arrows: true, 
  dropShadow: false, 
  cluetipClass: 'jtip'}
);
```
this sticky clueTip has a fixed height. It's generally a good idea to make fixed-height clueTips sticky as well, just in case the content requires a scrollbar to read it fully.
View the HTML
```
<a class="jt" href="ajax5.htm" rel="ajax5.htm">
```
View the jQuery
```
$('a.jt:eq(2)').cluetip({
  cluetipClass: 'jtip', arrows: true, 
  dropShadow: false, 
  height: '150px', 
  sticky: true
});
```

Rounded Corners Theme

rounded corners theme and positioning by mouse:

View the HTML

<a href="ajax4.htm" rel="ajax4.htm" title="mouse positioned">

View the jQuery

$('ol.rounded a:eq(0)').cluetip({cluetipClass: 'rounded', dropShadow: false, positionBy: 'mouse'});

Another one with rounded corners theme. This one has "bottomTop" positioning: positioned under link, unless there isn't enough room (then over).
View the HTML
```
<a href="ajax4.htm" rel="ajax4.htm" title="bottom/top positioned">
```
View the jQuery
```
$('ol.rounded a:eq(1)').cluetip({cluetipClass: 'rounded', dropShadow: false, positionBy: 'bottomTop'});
```

non-caching ajax clueTip with rounded corners:

View the HTML

<a href="ajax4.htm" rel="ajax4.htm" title="rounded corners">

View the jQuery

$('ol.rounded a:eq(2)').cluetip({cluetipClass: 'rounded', dropShadow: false, sticky: true, ajaxCache: false});

ajax error: This one points to a file that does not exist.

View the HTML

<a href="ajax404.htm" rel="ajax404.htm">

View the jQuery

$('ol.rounded a:eq(3)').cluetip({cluetipClass: 'rounded', dropShadow: false});

this is the local content to load when the 'local' parameter is set to true. Currently it only works with an id selector.

Default

You can style your clueTips any way you want. Here are the three "themes" that come bundled with the plugin:

/***************************************
* Default
    cluetipClass: 'default' 
-------------------------------------- */

.cluetip-default {
  background: #d9d9c2;
}
.cluetip-default #cluetip-outer {
  position: relative;
  margin: 0;
  background: #d9d9c2;
}
.cluetip-default h3#cluetip-title {
  margin: 0 0 5px;
  padding: 8px 10px 4px;
  font-size: 1.1em;
  font-weight: normal;
  background-color: #87876a;
  color: #fff;
}
.cluetip-default #cluetip-inner {
  padding: 10px;
}
.cluetip-default span#cluetip-close { 
  text-align: right;
  margin: 0 5px 5px;
  color: #900;
}

/***************************************
* jTip
    cluetipClass: 'jtip'
-------------------------------------- */

.clue-right-jtip {
  background-image: url(arrowleft.gif);
  background-repeat: no-repeat;
  padding-left: 10px;
}
.clue-left-jtip {
  background-image: url(arrowright.gif);
  background-repeat: no-repeat;
  padding-right: 10px;
}

.cluetip-jtip #cluetip-outer {
  border: 2px solid #ccc;
  position: relative;
  background: #fff;
}

.cluetip-jtip h3#cluetip-title {
  margin: 0 0 5px;
  padding: 2px 5px;
  font-size: 16px;
  font-weight: normal;
  background-color: #ccc;
  color: #333;
}

.cluetip-jtip #cluetip-inner {
  padding: 0 5px 5px;
  display: inline-block;
}
.cluetip-jtip span#cluetip-close { 
  text-align: right;
  margin: 0 5px 5px;
  color: #900;
}

/***************************************
* Rounded Corners
   cluetipClass: 'rounded'
-------------------------------------- */

.cluetip-rounded {
  background: transparent url(bl.gif) no-repeat 0 100%;
  margin-top: 10px;
}

.cluetip-rounded #cluetip-outer {
  background: transparent url(tl.gif) no-repeat 0 0;
  margin-top: -12px;
}

.cluetip-rounded #cluetip-title {
  background: transparent url(tr.gif) no-repeat 100% 0;
  padding: 12px 12px 0;
  margin: 0 -12px 0 0;
  position: relative;
}
.cluetip-rounded #cluetip-inner {
  background: url(br.gif) no-repeat 100% 100%;
  padding: 5px 12px 12px;
  margin: 0 -12px 0 0;
  position: relative;
}

.cluetip-rounded span#cluetip-close { 
  text-align: right;
  margin: 0 5px 5px;
  color: #009;
  background: transparent;
}
.cluetip-rounded span#cluetip-close a {
  color: #777;
}
/* stupid IE6 HasLayout hack */
.cluetip-rounded #cluetip-title,
.cluetip-rounded #cluetip-inner {
  zoom: 1;
}

Rounded Corners

Known Issues and To Do

Here is a list of bugs and features I've been working on:

Insert an iFrame behind the clueTip to prevent the select list from poking through in IE6.
Allow sticky clueTips to be closed when a user clicks anywhere else on the page.
~~Add a "loading" image.~~ Done!
~~Allow clueTips to load content from same page.~~ Done!
~~Re-work the ajax options so they can be set as they would be with a regular $.ajax().~~ Done!
~~Optimize ajax loading to avoid multiple requests for the same clueTip content.~~ Done!
~~Allow clueTips to take advantage of Brian Cherne's hoverIntent plugin~~ Done!
~~Include some kind of .png alpha transparency fix for IE 6 and under.~~ Abandoned in favor of divs with reduced opacity

Downloads

ClueTip

clueTip files in jQuery's SVN repository : includes jquery.cluetip.js, demo files, and all dependencies.
clueTip demo on learningjquery.com

Dependencies

Dimensions Plugin in jQuery's SVN repository : includes jquery.dimensions.js, as well as minified and packed versions.
jquery.js : latest stable release
hoverIntent Plugin (optional) on Brian Cherne's web site : includes demos and source file.

clueTip : A jQuery Plugin

Credits

Features

Multiple Content Sources

Smart Positioning

Flexible Behavior

Many, Many Options

Setup

Link Prep

Examples

Default Style

Hover over me.

jTip Theme

Rounded Corners Theme

Default

Rounded Corners

Known Issues and To Do

Downloads