clueTip Plugin Beta
If you're a member of the jQuery discussion list, then you probably already know that I've been working on an ajax tooltip plugin, inspired by Cody Lindley's jTip plugin. Well, I'm finally ready to officially introduce it (even though Smashing Magazine somehow found out about it and included it in their list of 40+ Tooltips Scripts).
The new clueTip plugin allows you to easily set a link, or any other element, to show a tooltip when the user's mouse hovers over it. If the link includes a title attribute, its text becomes the heading of the clueTip.
The contents of the clueTip can come from a separate file via AJAX, an element on the current page when set to "local," or the title attribute with a designated delimiter.
The clueTip offers smart positioning and 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 comes with many options, all of which are documented in the source comments and on the demo page.
Using the clueTip Plugin
To use the plugin, add references to the jQuery source file, the Dimensions plugin, and clueTip itself in your page's <head>. You can optionally include the hoverIntent plugin as well. Finally, you'll need to include your custom script file. So, it'll end up looking something like this:
<script type="text/javascript" src="/scripts/jquery.js"></script>
<script type="text/javascript" src="/scripts/jquery.dimensions.js"></script>
<script type="text/javascript" src="/scripts/jquery.hoverIntent.js"></script>
<script type="text/javascript" src="/scripts/jquery.cluetip.js"></script>
<script type="text/javascript" src="/scripts/your-custom-script.js"></script>
Your custom script is where the magic happens. Here is what the code looks like for the three clueTips in the previous paragraphs (hover over the links with dotted bottom borders):
[js]$(document).ready(function() { $('a.basic-clue').cluetip(); $('a:contains(options)').cluetip({width: 520, sticky: true}); });[/js]Since the first two links above have a class of "basic-clue," they get the basic clueTip (line 2). The third one, which contains the string "options," gets a custom clueTip with a width of 520 pixels (line 3). Also, because the sticky option is set to true, its clueTip won't be removed until the user clicks on the "Close" text.
More Examples
Here are four more variations on the clueTip theme, just to give you an idea of what you can do:
1) Give the rel and href attributes different values, so the first is used on hover for the clueTip and the second is used on click for taking your there: jquery.com. By the way, it's a good idea to set the sticky option to true if you know the clueTip will have links in it. Otherwise, the user won't be able to get to those links.
The HTML is as simple as this: <a class="sticky-clue" rel="/cluefiles/blurb.html" href="http://jquery.com">jquery.com</a>. The jQuery is simple:
2) Assign the clueTip to a <span> element and populate the whole thing from its title attribute. For kicks, add a hoverClass: Show me the clueTip!
The HTML for it looks like this: <span title="clueTip heading,all of this beautiful text,is taken from the title attribute">Show me the clueTip!</span>
And the jQuery looks like this:
[js]$(document).ready(function() { $('span[title]').cluetip({ splitTitle: ',', hoverClass:'highlighter' }); });[/js]3) Activate the clueTip on click and use <div id="local-clue"> on the current page for the clueTip content:
you must click me to activate me
Here is the HTML: <a class="local" href="#local-clue" title="click to open/close clueTip">you must click me to activate me</a>
Here is the jQuery:
[js]$(document).ready(function() { $('a.local').cluetip({ local: true, attribute: 'href', activation: 'click' }); });[/js]4) Assign a clueTip to an img with an id of clue-image, using the alt attribute for the clueTip's title and the longdesc attribute for the AJAXed-in clueTip body. (Side note: I've always wanted to use the longdesc attribute. This is like a dream come true.) Make the clueTip "sticky" and put a custom "close" image at the bottom of it. To top it off, grab an XML file and process it. Try it out:
The HTML: <img id="clue-image" src="/images/boy-wonder.jpg" alt="The Boy Wonder Rides" longdesc="/cluefiles/heroes.xml" />
And the jQuery:
[js]$(document).ready(function() { $('#clue-image').cluetip({ width: 380, attribute: 'longdesc', titleAttribute: 'alt', sticky: 'true', closeText: '', closePosition: 'bottom', ajaxProcess: function(data) { var html = ''; $(data).find('hero[firstname=Ben]').each(function() { var $hero = $(this); html +=''; html += '' + $hero.attr('firstname') + ' loves to ' + $('activity', $hero).text() + '
'; }); return html; }, ajaxSettings: { dataType: 'xml' } }); });[/js]There are many other things you can do with your clueTips. And you can change the default styles located in jquery.cluetip.css. Play around and have fun!
What's Next
Your feedback is most welcome. I'll be adding clueTip to the new jQuery plugin repository within the next few weeks, but I'd like to make sure it works well for others before I do. If you spot any bugs or want me to add a feature, you can post a comment below or on the jQuery discussion list/ Google Group.
Here are some download links to get you going:
ClueTip
clueTip files in jQuery's SVN repository : includes jquery.cluetip.js, demo files, and all dependencies.Not recommended. See the Update below.- clueTip demo on learningjquery.com
Dependencies
- Dimensions Plugin
- jquery.js : only needed for jQuery versions 1.2.4 and below
- hoverIntent Plugin (optional) on Brian Cherne's web site : includes demos and source file.
Update
This plugin is a work in progress, in case you couldn't tell. I've changed it a lot since posting this entry, so please refer to these pages from now on:
- clueTip Project Page on GitHub. You can grab the latest release and file bug reports there.
- clueTip Info & Demo Page. You can take the plugin for a spin and learn how to use it there.
