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):

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('a.basic-clue').cluetip(); 
  3.   $('a:contains(options)').cluetip({width: 520, sticky: true});
  4. });

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:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('a.sticky-clue').cluetip({sticky: true}); 
  3. });

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:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('span[@title]').cluetip({
  3.     splitTitle: ',',
  4.     hoverClass:'highlighter'
  5.   });
  6. });

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:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('a.local').cluetip({
  3.     local: true,
  4.     attribute: 'href',
  5.     activation: 'click'
  6.   });
  7. });

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 Boy Wonder Rides
The HTML: <img id="clue-image" src="/images/boy-wonder.jpg" alt="The Boy Wonder Rides" longdesc="/cluefiles/heroes.xml" />

And the jQuery:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('#clue-image').cluetip({
  3.     width: 380,
  4.     attribute: 'longdesc',
  5.     titleAttribute: 'alt',
  6.     sticky: 'true',
  7.     closeText: '<img src="/images/cross.png" alt="close" />',
  8.     closePosition: 'bottom',
  9.     ajaxProcess: function(data) {
  10.       var html = '';
  11.       $(data).find('hero[@firstname=Ben]').each(function() {
  12.         var $hero = $(this);
  13.         html +='<img src="' + $('photo', $hero).text() + '" alt="" />';
  14.         html += '<p>' + $hero.attr('firstname') + ' loves to ' + $('activity', $hero).text() + '</p>';
  15.       });
  16.       return html;
  17.     },
  18.     ajaxSettings: {
  19.       dataType: 'xml'
  20.     }
  21.   });
  22. });

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

Dependencies

  • Dimensions Plugin
  • jquery.js : latest stable release
  • hoverIntent Plugin (optional) on Brian Cherne's web site : includes demos and source file.
This kind of clueTip could be used for a footnote. With JavaScript off, it would just show up in its original place.

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 at the jquery.com plugin repository. You can grab the latest "stable" 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.

28 Responses to “clueTip Plugin Beta”

  1. jamjammo Says:
    July 13th, 2007 at 5:15 pm

    I think I would most likely use the bottom method, as photo gallery script type thingie.

  2. Brandon Says:
    July 17th, 2007 at 3:14 am

    I'm trying to get thickbox and cluetip to work together, but I can't seem to figure it out. I'm using the 'local' and 'sticky' attributes. Within the cluetip are links to external pages that I'd like to be opened on the same page with thickbox. Do you know of any way to make this work? I'm open to other suggestions if anyone wants to offer them. Thanks for the great plugin!

  3. Mitchell Waite Says:
    July 19th, 2007 at 12:15 am

    This is fantastic. Is there an example for #4, the one with the image in the cluetip box?

  4. Justin Says:
    July 19th, 2007 at 3:48 am

    Hey, Karl
    Great work! I'm loving clueTip. It's saving a lot of time being able to use "local" content. I do have a question though. How do you get it to work on an area for an image map? Currently it flickers on and off at the top left of the image (in firefox anyway). I'm working on a hot project and getting a solution for this would be VERY helpful. Thanks!

    J

  5. Justin Says:
    July 19th, 2007 at 4:15 am

    I just noticed another issue, Karl. My page has a Flash animation in the header and for some reason, when you mouse over one of the image map links for the tooltip the Flash content starts over. Any thoughts on that?

    J

  6. Karl Says:
    July 19th, 2007 at 9:42 am

    Mitchell, if you hover the mouse over the photo of the boy long enough, you should see the clueTip appear. Admittedly, there is too much lag there, especially with a slow connection. I'll be releasing beta 2 tonight or tomorrow, which will show a "loader gif" until the content is successfully retrieved.

    Justin, I'm terrible at dealing with Flash problems, but I'd be happy to take a look at both issues you're having. Do you have a URL that I can see? If you don't want to publish the URL in the comments here, feel free to use the contact form.

  7. Karl Says:
    July 22nd, 2007 at 7:41 pm

    FYI, everyone. I worked with Justin through email and came up with a solution to his problem with the image maps. The fix is now in the plugin code.

  8. Nir Says:
    August 4th, 2007 at 6:46 pm

    Thanks a lot for this amazing tooltip!

    I have A request...
    Can you add the functionality that keep the tool tip on the screen and only disappear when we move out from the tooltip box.

    I think it was Bruno Goyanna who solved it on your previous jTip project.
    (http://www.learningjquery.com/2006/10/updated-plugin-jtip#comment-5044)

    Thanks A lot for the great help you provide on the web.

  9. vandal Says:
    August 16th, 2007 at 11:20 am

    When I use more than one tooltip in a page, and If i over tooltip links one by one then for slow connection shows me previous tooltip's contents(title and inner data).

    Any comments or suggestions?

  10. Milton Says:
    September 13th, 2007 at 12:35 pm

    Karl-

    I'm having the same type of problem Justin had; I'm using the JW FLV Player, and anytime cluetip pops up its Jtip-styled on hover, the FLV player either starts the video over, or skips to a strange place in the video timeline...

    I downloaded the plugin after your July 22nd posting. The bug doesn't occur in Safari for Mac or IE 6 for windows, but in Firefox, both platforms, it has this issue.

    One thing I haven't tried yet is using the jquery method of referencing the FLV player (right now, I'm just using the standard FLV javascript within the webpage itself) - so, I'm hoping that using jquery for the FLV reference will fix the problem... do you think this has any chance of fixing the problem, or is it something more complex?

  11. Karl Says:
    September 13th, 2007 at 12:56 pm

    Hi Milton, one thing that has worked for Justin and others is to append the clueTip to a relatively positioned wrapper div rather than to the <body> tag. You can do that with the latest version (0.9). Just add this line inside your $(docment).ready() and before your lines containing .cluetip():

    $.cluetip.setup({insertionElement: '#wrapper'});

    You'll need to change "#wrapper" to whatever your wrapper div is named.

    Hope that helps.

  12. John Says:
    October 3rd, 2007 at 1:16 am

    Is there anyway to pass php variables on the hover. I have a link that has an rel of "map.php?cat_id=3". This page works fine if you just go to it, it basically is using the google maps API to select clients that have a cat_id of 3.

    I couldnt get the page to load at all (I would get an 'error loading contents' on the bottom so i added the data-type function and instead of xml or html i put in 'php'. Now the page will load, but only the html portion of the page (the header). None of the google maps is showing up because no variable is getting passed through. Any suggestions?

    btw i am using mysql database to store all my information.

  13. John Says:
    October 3rd, 2007 at 1:27 am

    After some more testing i was actually wrong. The php variables are getting passed to the page. I can echo out cat_id and it displays 3. The problem seems that no query is getting executed. I made a simple test sql statement and tried to echo it and nothing came up. Any ideas on how to get the php to query the database? Maybe make the page wait to display until all queries are executed (normally the page will take 2-3 seconds to load because of the amt of queries i need to execute. The hover link displays the html instantly which makes me think there is not enough time to execute anything).

    -John

  14. Massimiliano Balestrieri Says:
    October 30th, 2007 at 12:36 pm

    just one thing...

    //[...]
    $cluetip.css({backgroundPosition: bgPos});
    $cluetip.bgIframe();//include bgiframe js

    no?

    WONDERFUL WORK
    bye max

  15. Anish Aggarwal Says:
    November 8th, 2007 at 7:54 pm

    Karl, I am still having the same problems where the Flash viewer dissappears and restarts once any cluetip action is activated. I tried to put the change:

    jQuery.cluetip.setup({insertionElement: '#wrapper'});

    into my onReady function but it didn't seem to work. Is there something I am missing? BTW, what does the insertionElement do?

    Thanks in Advance...

  16. Karl Says:
    November 8th, 2007 at 8:40 pm

    Hi Anish,

    I turns out that this problem has to do with setting height or width on an element when its parent doesn't have a position defined. If in your stylesheet you can set position: relative to body or #wrapper or whatever other element you want to append the clueTip to, that should fix the problem.

  17. Anish Says:
    November 12th, 2007 at 6:19 pm

    Thanks Karl. It looks liked that worked for the video but now I am getting another problem where when I roll-over the item the clue-tip is showing up about 100 pixels right of where it initially was before the position change. I am using positionBy: 'mouse' for my clue-tips so i should expect it to be near the mouse but it is not. Can you help?

    Great module, btw...

  18. Paul Says:
    January 3rd, 2008 at 1:57 pm

    FYI, everyone. I worked with Justin through email and came up with a solution to his problem with the image maps. The fix is now in the plugin code.

    I am having trouble getting the cluetip to show as well. Would you mind sharing the solution you came up with Justin?

    Thanks

  19. Rob Says:
    January 29th, 2008 at 3:19 pm

    I have the same issue as Paul regarding image maps. Can you please post an example?
    Thanks.

  20. Rob Says:
    January 29th, 2008 at 3:50 pm

    I got it working with image maps. Great plugin! Hope this helps someone else out.
    - Rob

    jQuery code:

    
$(document).ready(function() {
    $('area.tips').cluetip({
        splitTitle: '|',
        arrows: true,
        dropShadow: false,
        cluetipClass: 'jtip'
    }) ;
}) ;

    HTML

    
<map>
    <area shape="rect"
        coords="269,432,277,440"
        href="link.html"
        alt="my alt tag"
        title="Title|Content"
        class="tips" />
</map>
  21. haidah Says:
    February 26th, 2008 at 6:11 am

    my image magic working but not working if i'm using explorer can someone help

  22. erwan Says:
    April 24th, 2008 at 12:32 pm

    Hi, used the map technique with ids

    But seems that the default shape doesn't create cluetips.


    <area shape="default" href="#" alt="" class="tips" rel="#siege" title='my title' / >

    any hint ?

  23. Jon Says:
    May 8th, 2008 at 5:55 am

    I'm having troubles with getting the cluetips to appear, specifically just with the area tag.
    In my attempts, the problem occurs in IE 6 and 7 (works fine with firefox/safari).
    From the looks of thing's I don't seem to be the only person experiencing difficulties. So has anyone found a solution or a workaround for this?

    My code looks like this:

    <script type="text/javascript">
$(document).ready(function(){
	$('area.projects-s').cluetip({cluetipClass: 'rounded', dropShadow: false, sticky: true, ajaxCache: false, arrows: true, width: 275});
	$('area.projects-m').cluetip({cluetipClass: 'rounded', dropShadow: false, sticky: true, ajaxCache: false, arrows: true, width: 350});
	$('area.projects-l').cluetip({cluetipClass: 'rounded', dropShadow: false, sticky: true, ajaxCache: false, arrows: true, width: 425});
});
</script>

    <div id="map">
        <img src="map_page_test.jpg" border="0" usemap="#Map" />
	<map name="Map" id="Map">
            <area shape="rect" class="projects-s" coords="458,249,471,263" href="ajax1.htm" rel="ajax1.htm" />
            <area shape="rect" class="projects-m" coords="489,298,502,312" href="ajax2.htm" rel="ajax2.htm" />
            <area shape="rect" class="projects-l" coords="462,327,475,342" href="ajax3.htm" rel="ajax3.htm" />
            <area shape="rect" class="projects-s" coords="507,342,519,356" href="ajax4.htm" rel="ajax4.htm" />
            <area shape="rect" class="projects-l" coords="475,393,489,408" href="ajax5.htm" rel="ajax5.htm" />
            <area shape="rect" class="projects-m" coords="555,413,565,425" href="ajax6.htm" rel="ajax6.htm" />
        </map>
    </div>
  24. KLaus Says:
    May 14th, 2008 at 10:39 am

    Hi,
    is it possible to load content of external file for a link preview?

    thanks
    Klaus

  25. Antreas Says:
    May 21st, 2008 at 2:56 pm

    Hi all thanks for this wonderfull plugin.
    I have a problem trying to make it load content from a php page. Basically i have the same problem as John in posts 12 and 13. I can't get it to call a php page which queries a database and shows the results. Only the static parts of the php page called are shown. Have anyone found a solution about this?
    Thanks.

  26. Karl Swedberg Says:
    May 22nd, 2008 at 8:37 am

    Hi Antreas,

    What you need to do to pass a variable to the PHP page is to use the ajaxSettings clueTip option, which is just a surrogate for $.ajax(). So something like this should work:

    $('someelements').cluetip({
    ajaxSettings: {
        dataType: 'html', // <-- change this if a different  data type is being returned
        data: "name=Karl&location=Siberia"
    }
});

    You can read more details about the ajax method and see more examples of the data option in the jQuery documentation.

    Hope that helps.

  27. Antreas Says:
    May 22nd, 2008 at 3:54 pm

    karl it worked like a charm. thanks man you are a life and time saver. :-)

  28. mmalaka Says:
    July 1st, 2008 at 12:10 pm

    I tried this for the Image Map on the Area tag and still it is not working, I can not see the tooltip I can only see the standard one...

    Any advice

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <code> <pre> <em> <i> <li> <ol> <strike> <strong> <ul>

IMPORTANT: If you wish to post code examples, please wrap them in <code> tags. Multi-line code should be wrapped in <pre><code> </code></pre> Also, use &lt; instead of < and &gt; instead of > in the examples themselves. Otherwise, you could lose part of the comment when it's submitted.