Intro

Prototip allows you to easily create both simple and complex tooltips using the Prototype javascript framework. If you also use Scriptaculous you can even add some nice effects to them.

Prototip 2 is now available!

A new version of this script is available, check out the Prototip 2 website for all the details.

note: Upgrading to Prototip 2 is recommended, the 1.x version will no longer be upgraded.

News

Prototip 1.3 - Ajax tooltips

April 15 - 2008 : Nick Stakenburg

Finally Ajax tooltips that just work! The much requested feature to have Ajax support on tooltips has been implemented with this release. No longer will you need to use workarounds to get this done, a solid implementation is now available that works with all the different types of tooltips. The Advanced section has more details on this update.

If you have feedback or feature requests, leave a message on the Forum.

Enjoy!

Demos

Installation

Include Prototype 1.6.0.2 in your header. If you are using the effects, also add Scriptaculous 1.8.1. After both are included, add Prototip.

<script type='text/javascript' src='js/prototype.js'></script>
<script type='text/javascript' src='js/scriptaculous.js?load=effects'></script>
<script type='text/javascript' src='js/prototip.js'></script>

If you want to make the filesize smaller, have a look at Protopacked. It contains compressed versions of Prototype and Scriptaculous. You can have the required files, Prototype and effects.js, starting at 28kb.

Add prototip.css to your header.

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

Make sure these images are in the same directory as prototip.css

close.gif, close_hover.gif, close_hover_red.gif and classic_toolbar.gif

How to use

Creating a tooltip is as easy as:

new Tip(element, 'content');

To create a more advanced tooltip you can add an optional thirth parameter with options:

new Tip(element, 'content', {title: 'this tooltip has a title'});
All the options you can use - click to show/hide
new Tip(
  element,                 // the id of your element
  content,                 // a string or an element
  {
    ajax: false,           // or {
                           //   url: 'page.php',
                           //   options: {}
                           // }
                           // 
                           // Note:
                           // Don't use the content argument when you use this!
                           // See the 'Advanced' part of the site for details

    className: 'default',  // or your own class
    closeButton: false,    // or true
    duration: 0.3,         // duration of the effect, if used
    delay: 0.2,            // seconds before tooltip appears
    effect: false,         // false, 'appear' or 'blind'
    fixed: false,          // follow the mouse if false
    hideAfter: false,      // hides after seconds of inactivity,
                           // not hovering the element or the tooltip
    hideOn: 'mouseout'     // any other event, false or:
                           // { element: 'element|target|tip|closeButton|.close',
                           //   event: 'click|mouseover|mousemove' }
    hook: false,           // { target: 'topLeft|topRight|bottomLeft|bottomRight|
                           //     topMiddle|bottomMiddle|leftMiddle|rightMiddle',
                           //   tip: 'topLeft|topRight|bottomLeft|bottomRight|
                           //           topMiddle|bottomMiddle|leftMiddle|rightMiddle' }
    offset: {x:16, y:16}   // or your own, example: {x: 30, y: 200}
    showOn: 'mousemove',   // or any other event
    target: 'anotherId',   // make the tooltip appear on another element
    title: false,          // or a string, example: 'tip title'
    viewport: true         // keep within viewport, false when fixed or hooked
  }
);

Hooking

Styling

Tooltips can be styled using CSS. prototip.css shows a few examples on how to do this. Here is one of those examples:

The default class used by prototip is 'default', you can overwrite this class with your own by using the className option:

new Tip(element, 'content', { className: 'myClass' });

Advanced

Ajax tooltips

Ajax tooltips allows you to pull content from an url. Note that the second argument, where you would normally put a string or an element, is left out! Use url to set the location for the Ajax Request. options can hold anything you would otherwise set on an Ajax.Request as options. See the Prototype API on Ajax.options for more details

new Tip('myTip', {
  ajax: {
    url: '/include/ajax.php',
    options: {
      onComplete: function() {
        alert('ajax content loaded');      
      }
    }
  }
});

Custom events

Using the custom events prototip:shown and prototip:hidden you can call a function when your tooltip opens or closes. You do this by observing the element that opens the tooltip. If you have firebug installed you can run the examples below from your console, this one works on demo 8:

$('tip8').observe('prototip:shown', function() {
  this.pulsate({ pulses: 1, duration: 0.3 });
});

Custom events bubble up, so we could monitor let's say the document to do something when every tooltip hides. event.element() is used in the example below to find the element that opened the tooltip. In the example above 'this' was sufficient since it refers to the observed element, event.element() is used in the example below since we don't know the element that triggered the event.

document.observe('prototip:hidden', function(event) {
  $('logo').shake();
  event.element().shake();
});

Automatically add tooltips

Here's how to automatically add a tooltip to every link in the page by using it's rel attibute, after the page has finished loading. $$ accepts a CSS selector, so it could also be used to target different groups of elements.

document.observe('dom:loaded', function(){
  $$('a[rel]').each(function(element){
    new Tip(element, element.rel);
  });
});

Troubleshooting

Tooltips are not showing up.

Give your page a doctype, I recommend using Strict or Transitional. Also make sure prototip.css is included.

The effects don't work no matter what I try.

You must have effects.js from the Scriptaculous package. Don't download Scriptaculous from my site, but get the full package at script.aculo.us

My tooltips look different from those on your website.

This could be because prototip.css is not included. It also happens when your own css is conflicting with prototip.css. Remember not to set things globally in your own css files, rules like: div { display: inline; } are bad practice. Target your elements better, this will prevent conflicts. When your css is properly coded you should have no problem implementing Prototip.

It's still not working.

Make sure your page validates using validator.w3.org before posting for support on the Prototip Forum.

I don't like the filesize.

Gzip your Javascript files. If gzipping is not an option you should look into Protopacked. You can get the required files combined, Prototype and Scriptaculous effects.js, starting at 28kb.

License

Permission to use Prototip on your domain is required and can be obtained by paying a small fee. For non-commercial domains this will allow you to use Prototip under a Creative Commons Attribution-Noncommercial-No Derivative Works License. When you get permission for a commercial domain you may use Prototip under the terms of the Creative Commons Attribution-No Derivative Works License.

  • Non-Commercial

    Single domain

    A small fee is required for non-commercial use.
  • Non-Commercial

    Unlimited

    Get permission to use Prototip and future updates on all the non-commercial websites you develop in the future, at no further cost.
  • Commercial

    Single domain

    This will give you permission to use Prototip on a single commercial domain.

    When is my website considered commercial?

  • Commercial

    Unlimited

    With unlimited permission you are allowed to use Prototip and all future updates on any commercial website you develop in the future, at no further cost.

Don't have a Paypal account?

Download

Note: When updating, make sure to replace all files.

Changelog

Toggle all changelog entries
*1.3.5.1* (May 18, 2008)

* Made sure that ajax tooltips opening on click don't cancel their loading when you mouseout [jakobsen]


Contact

Use the Prototip Forum for support related questions, feedback, feature requests and bug reports.

For anything non-support related you can contact me at nick@nickstakenburg.com. Please use the forum to get support.

prototype, scriptaculous, tooltip, ajax, javascript, web2.0, Creative Commons by-nc-nd License, © 2008-2009 Nick Stakenburg

defining tooltips, cross-browser tooltip, dhtml tooltip, tooltip library, customize tooltips