25 | 
3 | 
12 | 
',
27 | truncate: 60
28 | });
29 | $('a.load-local').cluetip({local:true, hideLocal: true, sticky: true, arrows: true, cursor: 'pointer'});
30 | $('#clickme').cluetip({activation: 'click', sticky: true, width: 650});
31 | $('ol:first a:last').cluetip({tracking: true});
32 |
33 | // jTip theme
34 | $('a.jt:eq(0)').cluetip({
35 | cluetipClass: 'jtip',
36 | arrows: true,
37 | dropShadow: false,
38 | sticky: true,
39 | mouseOutClose: true,
40 | closePosition: 'title',
41 | closeText: '
Now ThemeRoller Ready (as of clueTip 1.1).
38 |
39 |
62 |
81 |
82 | Important: This plugin is no longer being maintained.
40 | 41 |I originally wrote clueTip back in 2006 as my first attempt at a jQuery plugin. If I were to write it now, I would do it completely differently. However, I don't have the time or energy to work on it. The good news is that you can use any one of a number of better tooltip plugins. Here are a few:
42 |-
43 |
- jQuery UI Tooltip 44 |
- Tooltipster 45 |
- qTip2 46 |
Overview
48 |The clueTip plugin allows you to easily show a fancy tooltip when the user's mouse hovers over (or, optionally, clicks on) any element you designate in your script. If the element includes a title attribute, its text becomes the heading of the clueTip.
If you like this plugin and you're feeling generous, perhaps you'd also like to visit my amazon.com wish list?
50 |Quick Start Guide
51 | Showing the most basic clueTip can be achieved in two easy steps. 52 |Add HTML markup to your page for elements that you want to invoke a clueTip. By default, the clueTip plugin will use the
53 | rel attribute to load contents into the tooltip body via AHAH.
54 | <!-- use ajax/ahah to pull content from fragment.html: -->
55 | <p><a class="tips" href="fragment.html" rel="fragment.html">show me the cluetip!</a></p>
56 |
57 | <!-- use title attribute for clueTip contents, but don't include anything in the clueTip's heading -->
58 | <p><a id="houdini" href="houdini.html" title="|Houdini was an escape artist.|He was also adept at prestidigitation.">Houdini</a></p>
59 | Include the jQuery core file and the clueTip plugin in the
61 | <head> of your document. You may optionally include the hoverIntent plugin as well. After these scripts are referenced, you can reference a custom script file to invoke your clueTips (preferred) or enter the script directly in the <head> (shown below). You should also include the clueTip stylesheet (jquery.cluetip.css) after the scripts. 62 |
<script src="jquery.js" type="text/javascript"></script>
63 | <script src="jquery.hoverIntent.js" type="text/javascript"></script> <!-- optional -->
64 | <script src="jquery.cluetip.js" type="text/javascript"></script>
65 |
66 | <script type="text/javascript">
67 | $(document).ready(function() {
68 | $('a.tips').cluetip();
69 |
70 | $('#houdini').cluetip({
71 | splitTitle: '|', // use the invoking element's title attribute to populate the clueTip...
72 | // ...and split the contents into separate divs where there is a "|"
73 | showTitle: false // hide the clueTip's heading
74 | });
75 | });
76 | </script>
77 | <link rel="stylesheet" href="jquery.cluetip.css" type="text/css" />
78 | You can change the default style and behavior in many ways. See API / Options for details.
80 |
83 |
167 | This plugin is no longer being maintained.
84 |See the overview for a list of alternative tooltip plugins.
85 |clueTip Plugin Features
86 |
87 |
166 | -
88 |
- Multiple Content Sources 89 |
- Smart Positioning 90 |
- Flexible Behavior 91 |
- Style Variety 92 |
95 |
104 | Multiple Content Sources
96 |The contents of the clueTip can come from one of these sources:
97 |-
98 |
- a separate file, via AHAH / AJAX 99 |
- an element on the same page, typically hidden 100 |
- 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
101 | - the return value of a function referenced in the first argument of
.cluetip().
102 |
105 |
141 | Smart Positioning
106 | The clueTip Plugin has 4 positioning modes, which you can change via the "positionBy" option. 107 |-
108 |
positionBy: 'auto'(default) 109 |-
110 |
- places the tooltip just to the right of the invoking element, but... 111 |
- if there is not enough room for the tooltip to be fully visible between the right edge of the invoking element and the right edge of the browser window, switches from the right side to the left side, but... 112 |
- if the invoking element is too close to the bottom edge of the browser window, adjusts the tooltip upwards until the whole tooltip is visible, but... 113 |
- if the tooltip is taller than the window (i.e. the viewable area), adjusts the tooltip back down until the tooltip's top is at the top edge of the browser window, but... 114 |
- position if the invoking element is so wide that the tooltip can't completely fit to the left or the right of it, places the tooltip to the right or left of the mouse, but... 115 |
- if the tooltip itself can't fit to the right or left of the mouse position, places the tooltip below the mouse position (centered horizontal if enough room), but... 116 |
- 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, puts the tooltip above the mouse position 117 |
119 | positionBy: 'mouse'120 |-
121 |
- places the tooltip to the right of the mouse position, but... 122 |
- if there is not enough room to the right, places the tooltip to the left of the mouse position, but... 123 |
- if the tooltip itself can't fit to the right or left of the mouse position, places the tooltip below the mouse position (centered horizontally if enough room), but... 124 |
- 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, puts the tooltip above the mouse position 125 |
127 | positionBy: 'bottomTop'128 |-
129 |
- places the tooltip below the mouse position (centered horizontally if enough room), but... 130 |
- 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, puts the tooltip above the mouse position 131 |
133 | positionBy: 'fixed'134 |-
135 |
- places the tooltip in the same location relative to the invoking element, regardless of where it appears on the page. 136 |
- the fixed position can be adjusted by modifying the number of pixels in the
topOffsetandleftOffsetoptions
137 |
139 |
142 |
152 | Flexible Behavior
143 |-
144 |
- The clueTip takes advantage of Brian Cherne's hoverIntent plugin if it's available. (Just include it in a
<script>tag if you want the clueTip to use it.)
145 | - It can be activated on hover or on click. 146 |
- It can fade in, slide down, etc. 147 |
- It can close when the invoking element is moused out or when the tooltip is moused out or when the user clicks a "close" link. 148 |
- It can cache the results of ajax requests—or not. 149 |
- It can be turned off 150 |
153 |
165 | Variety of Styles
154 |The clueTip Plugin comes with three themes: default, jTip, and rounded corners. Additional themes can be created by following the naming patterns in the stylesheet, jquery.cluetip.css. To apply one of the alternative themes, just indicate it in the cluetipClass option as 'jtip' or 'rounded'.
The "loading" image comes from this rule in the stylesheet:
156 |#cluetip-waitimage {
157 | width: 43px;
158 | height: 11px;
159 | position: absolute;
160 | background-image: url(wait.gif);
161 | }It can be turned off with the following option: waitImage: false
Other options that affect the visual appearance include hoverClass, arrows, dropShadow, and dropShadowSteps. Please see API / Options for more information.
168 |
305 |
306 | This plugin is no longer being maintained.
169 |See the overview for a list of alternative tooltip plugins.
170 | 171 |clueTip Plugin API / Options
172 | The clueTip Plugin API provides two methods, with many options. It also provides a custom event for closing the tooltip programmatically 173 |-
174 |
$.cluetip.setup(options)
175 | - Global defaults for clueTips. Will apply to all calls to the clueTip plugin. 176 |
{
178 | insertionType: 'appendTo', // how the clueTip is inserted into the DOM
179 | // possible values: 'appendTo', 'prependTo', 'insertBefore', 'insertAfter'
180 | insertionElement: 'body' // where in the DOM the clueTip is to be inserted
181 | }-
183 |
.cluetip(options)
184 | - Displays a highly customizable tooltip via ajax (default) or local content or the title attribute of the invoking element 185 |
$.fn.cluetip.defaults = { // default options; override as needed
187 | multiple: false, // Allow a new tooltip to be created for each .cluetip() call
188 | width: 275, // The width of the clueTip
189 | height: 'auto', // The height of the clueTip. more info below [1]
190 | cluezIndex: 97, // Sets the z-index style property of the clueTip
191 | positionBy: 'auto', // Sets the type of positioning. more info below [2]
192 | topOffset: 15, // Number of px to offset clueTip from top of invoking element. more info below [3]
193 | leftOffset: 15, // Number of px to offset clueTip from left of invoking element. more info below [4]
194 | local: false, // Whether to use content from the same page for the clueTip's body
195 | // (treats the attribute used for accessing the tip as a jQuery selector,
196 | // but only selects the first element if the selector matches more than one). more info below [5]
197 | hideLocal: true, // If local option is set to true, this determines whether local content
198 | // to be shown in clueTip should be hidden at its original location
199 | localPrefix: null, // string to be prepended to the tip attribute if local is true
200 | localIdSuffix: null, // string to be appended to the cluetip content element's id if local is true
201 | attribute: 'rel', // the attribute to be used for fetching the clueTip's body content
202 | titleAttribute: 'title', // the attribute to be used for fetching the clueTip's title
203 | splitTitle: '', // A character used to split the title attribute into the clueTip title and divs
204 | // within the clueTip body. more info below [6]
205 | escapeTitle: false, // whether to html escape the title attribute
206 | showTitle: true, // show title bar of the clueTip, even if title attribute not set
207 | cluetipClass: 'default',// class added to outermost clueTip div in the form of 'cluetip-' + clueTipClass. more info below [7]
208 | hoverClass: '', // class applied to the invoking element onmouseover and removed onmouseout
209 | waitImage: true, // whether to show a "loading" img, which is set in jquery.cluetip.css
210 | cursor: 'help',
211 | arrows: false, // if true, displays arrow on appropriate side of clueTip. more info below [8]
212 | dropShadow: true, // set to false if you don't want the drop-shadow effect on the clueTip
213 | dropShadowSteps: 6, // adjusts the size of the drop shadow
214 | sticky: false, // keep visible until manually closed
215 | mouseOutClose: false, // close when clueTip is moused out: false, 'cluetip', 'link', 'both'
216 | delayedClose: 50, // close clueTip on a timed delay
217 | activation: 'hover', // set to 'click' to force user to click to show clueTip
218 | clickThrough: true, // if true, and activation is not 'click', then clicking on a clueTipped link will take user to
219 | // the link's href, even if href and tipAttribute are equal
220 | tracking: false, // if true, clueTip will track mouse movement (experimental)
221 | closePosition: 'top', // location of close text for sticky cluetips; can be 'top' or 'bottom' or 'title'
222 | closeText: 'Close', // text (or HTML) to to be clicked to close sticky clueTips
223 | truncate: 0, // number of characters to truncate clueTip's contents. if 0, no truncation occurs
224 |
225 | // effect and speed for opening clueTips
226 | fx: {
227 | open: 'show', // can be 'show' or 'slideDown' or 'fadeIn'
228 | openSpeed: ''
229 | },
230 |
231 | // settings for when hoverIntent plugin is used
232 | hoverIntent: {
233 | sensitivity: 3,
234 | interval: 50,
235 | timeout: 0
236 | },
237 |
238 | // function to run just before clueTip is shown.
239 | // If the function returns false, the clueTip is NOT shown
240 | // It can take a single argument: the event object
241 | // Inside the function, this refers to the element that invoked the clueTip
242 | onActivate: function(event) {return true;},
243 |
244 | // function to run just after clueTip is shown. It can take two arguments:
245 | // the first is a jQuery object representing the clueTip element;
246 | // the second a jQuery object represeting the clueTip inner div.
247 | // Inside the function, this refers to the element that invoked the clueTip
248 | onShow: function(ct, ci){},
249 |
250 | // function to run just after clueTip is hidden. It can take two arguments:
251 | // the first is a jQuery object representing the clueTip element;
252 | // the second a jQuery object represeting the clueTip inner div.
253 | // Inside the function, this refers to the element that invoked the clueTip
254 | onHide: function(ct, ci){},
255 |
256 | // whether to cache results of ajax request to avoid unnecessary hits to server
257 | ajaxCache: true,
258 |
259 | // process data retrieved via xhr before it's displayed
260 | ajaxProcess: function(data) {
261 | data = data.replace(/<(script|style|title)[^<]+<\/(script|style|title)>/gm, '').replace(/<(link|meta)[^>]+>/g,'');
262 | return data;
263 | },
264 | // can pass in standard $.ajax() parameters. Callback functions, such as beforeSend,
265 | // will be queued first within the default callbacks.
266 | ajaxSettings: {
267 | // error: function(ct, ci) { /* override default error callback */ },
268 | // beforeSend: function(ct, ci) { /* called first within default beforeSend callback */ },
269 | dataType: 'html'
270 | }
271 | };-
273 |
$(document).trigger('hideCluetip')
274 | - Hides any currently visible cluetip. 275 |
$('some-already-initialized-link').trigger('showCluetip')
288 | - Triggers the cluetip to be shown for a particular element on which
.cluetip()has already been called.
289 |
290 |
276 | // example for how you might do this with touch devices
277 | $('body').bind('touchstart', function(event) {
278 | event = event.originalEvent;
279 | var tgt = event.touches[0] && event.touches[0].target,
280 | $tgt = $(tgt);
281 |
282 | if (tgt.nodeName !== 'A' && !$tgt.closest('div.cluetip').length ) {
283 | $(document).trigger('hideCluetip');
284 | }
285 | });
286 | -
292 |
- height: Setting a specific height also sets <div id="cluetip-outer"> to "overflow:auto" 293 |
- positionBy: Available options are 'auto', 'mouse', 'bottomTop', 'topBottom', fixed'. 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 (and 'topBottom' for vice versa) — rather than right or left of the elemnent and flush with element's top. Change to 'fixed' if you want the clueTip to appear in exactly the same location relative to the linked element no matter where it appears on the page. Use 'fixed' at your own risk. 294 |
- topOffset:For all but positionBy: 'fixed', the number will be added to the clueTip's "top" value if the clueTip appears below the invoking element and subtracted from it if the clueTip appears above. For positionBy "fixed", the number will always be added to the "top" value, offsetting the clueTip from the top of the invoking element. 295 |
- leftOffset: For all but positionBy: 'fixed', the number will be added to clueTip's "left" value if the clueTip appears to the right of the invoking element and subtracted if the clueTip appears to the left. For positionBy "fixed", the number will always be added to the "left" value of the clueTip, offsetting it from the right side of the invoking element. 296 |
- local: for example, using the default tip attribute, "rel", you could have a link — <a href="somewhere.htm" rel="#someID"> — that would show the contents of the element in the DOM that has an ID of "someID."
297 | Important: If you use any selector other than a simple ID, the plugin will match the index of the element with the index of the invoking element among all selected elements. For example, if you call299 |
$('a').cluetip({local: true})and you have two links withrel="div.foo", the first link will display the contents of the firstdiv class="foo"and the second link will display the contents of the seconddiv class="foo". 298 |
300 | - splitTitle: if used, the clueTip will be populated only by the title attribute 301 |
- cluetipClass: this is also used for a "directional" class on the same div, depending on where the clueTip is in relation to the invoking element. The class appears in the form of 'cluetip-' + direction + cluetipClass. 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. 302 |
- arrows: UPDATE: this option displays a div containing an arrow background image. Arrow images are set using the background-image property in the CSS. The direction of the arrow changes depending on which side of the invoking element the clueTip appears. The arrows option sets the background-position of the cluetip div so that the arrow will accurately point to the invoking element, regardless of where it appears in relation to it. 303 |
307 |
368 | Frequently Asked Questions
308 |-
309 |
- Is clueTip still being maintained? 310 |
- No. It had a good run, but it's old and tired and in need of rest. Take a look at the overview for a list of alternative tooltip plugins. 311 | 312 |
- How is clueTip licensed? 313 |
-
314 |
The clueTip plugin is licensed the same way as the jQuery core file: under the MIT license. The top of the jquery.cluetip.js file has this notice:
315 |Licensed under the MIT license:
317 |
316 | * http://www.opensource.org/licenses/mit-license.php
318 | - What versions of jQuery is the clueTip Plugin compatible with? 319 |
- As of clueTip version 1.06, the plugin is compatible with version 1.3.2 or later. Previous clueTip versions are compatible with jQuery 1.2.6, though 1.3.2 or later is recommended. 320 |
- Does the clueTip Plugin have any dependencies on other plugins? 321 |
- No. However, optional plugins that can be used in conjunction with the clueTip plugin include hoverIntent and bgIframe. 322 |
- How do I get clueTip to work on elements that have been inserted via ajax after the page loads? 323 |
- You can call the
.cluetip()method on those elements from within the ajax method's callback function. For example: 324 |
329 |$.get('/path/to/file', function(html) { 325 | var newHtml = $(html); 326 | newHtml.appendTo('#some-elememnt'); 327 | newHtml.find('a').cluetip(); 328 | });
330 | - How do I get clueTip to show ajaxed content that has changed on the server? 331 |
- There are a number of options available for working with dynamic content. By default, the
ajaxCachefunction is set totrue. This reduces the number of http requests made to the server. However, it doesn't account for possible changes to the ajaxed data. If the contents of a particular clueTip will be updated on the server between invocations, you may want to setajaxCache: false. 332 |
333 | - How do I programmatically close (hide) a clueTip? 334 |
- If you want to trigger a clueTip to close, based on some other interaction, you can use the following code:
$(document).trigger('hideCluetip');
335 | - Why don't the styles that I've applied to my local content carry over once they're inside a clueTip? 336 |
- When using an element on the same page to populate the clueTip's content, the plugin clones that element. Because of potential problems caused by duplicate IDs within a page, the plugin also, by default, adds a suffix to the ID of the cloned element. If you have tied styles to the original ID, they won't be carried over. You can either give the
localIdSuffixan empty string ( '' ) for its value or add the ID to your stylesheet rule.
337 | - Why don't form elements within a clueTip update when I tell them to? 338 |
- If you attempt to update an element based on its ID, 339 |
- How do I add a delay before showing or closing the clueTip? 340 |
- While the clueTip plugin itself doesn't have a mechanism for delaying responses, it can take advantage of the optional hoverIntent plugin. To delay the showing of a clueTip, use the
intervalproperty of thehoverIntentoption; to delay its hiding, use thetimeoutproperty. Both properties are measured in milliseconds. For example, the following sets both the show and the hide delays to 750 milliseconds (3/4 second): 341 |
349 | See hoverIntent plugin's documentation for details.$('a').cluetip({ 342 | hoverIntent: { 343 | sensitivity: 1, 344 | interval: 750, 345 | timeout: 750 346 | } 347 | }); 348 |
350 | - Why are the clueTips hidden behind my Flash elements? 351 |
This is a common problem when trying to layer a DOM element over a Flash object. To avoid it, you need to set <param name="wmode" value="transparent" /> inside the <object></object> tags and/or wmode="transparent" as an attribute of the <embed /> tag. For example, your HTML might look like this:
352 | 353 |
365 |<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" 354 | codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab" 355 | width="500" height="300"> 356 | <param name="movie" value="test.swf" /> 357 | <param name="quality" value="high" /> 358 | <param name="wmode" value="transparent" /> 359 | 360 | <embed src="test.swf" quality="high" wmode="transparent" 361 | pluginspage="http://www.macromedia.com/go/getflashplayer" 362 | type="application/x-shockwave-flash" width="500" height="300" /> 363 | </object>364 |
366 |
369 |
376 | clueTip Plugin Credits
370 | 371 |-
372 |
- Originally inspired by Cody Lindley's jTip 373 |
- Huge thanks to Jonathan Chaffer, Glen Lipka, Torben Schreiter, Dan G. Switzer, Jörn Zaefferer, Shelane Enos, Hector Santos, and the many others who helped report and fix bugs and suggest features. 374 |
377 |
389 | This plugin is no longer being supported.
378 |See the overview for a list of alternative tooltip plugins.
379 | 380 |Download
381 |The plugin is available on Github, where it is updated more frequently with incremental improvements and bug fixes: clueTip on Github
382 |