Opentip | Documentation

Documentation

To get started, download the latest opentip package and unzip it in YOUR_PATH.
Then, in your HTML, include prototype.js, opentip.css, opentip.js and excanvas.js.
Obviously if you already have prototype or excanvas include, all you need are the 2 opentip files.
You do not have to include scriptaculous! Opentip uses css3 animations when available. Scriptaculous is just a fallback for older browsers.
I recommend using Google APIs for prototype and scriptaculous.

<script type="text/javascript" src="SOME_PATH/prototype.js"></script>
<script type="text/javascript" src="SOME_PATH/scriptaculous.js"></script>
<script type="text/javascript" src="YOUR_PATH/opentip.js"></script>
<script type="text/javascript" src="YOUR_PATH/excanvas.js"></script>
<link rel="stylesheet" type="text/css" href="YOUR_PATH/opentip.css" />

An opentip can be created in three different ways. All are completely equivalent:

<div ot="content"
  ot-title="optional title"
  ot-show-effect="appear" ...></div>

<div onmouseover="javascript:Tips.add(
  this,
  event,
  'content',
  'optional title',
  { showEffect: 'appear', ... });"></div>

<script type="text/javascript">
  $('elementId').addTip(
    'content',
    'optional title',
    { showEffect: 'appear', ... });
</script>

The following is also possible, but really just a hack I implemented for compatibility reasons with other tooltip classes.

// When called externally:
new Tip('elementId', etc...);
// When called as event (eg: onmouseover or onclick): 
new Tip(this, event, etc...);

Those are the possible ways to pass arguments:

$('elementId').addTip('content', 'title', { options...});

$('elementId').addTip('content', { options...});

$('elementId').addTip({ options...}); // Only makes sens with AJAX

Note, that when using html element tags, all options you could pass with the options object can be specified as element tags. Simply prefix them with ot- and use dashes.

Options

The options object contains following values:

classNameThe class name to be used.'standard'

stemThree possible values:
false: no stem
true: stem at tipJoint POSITION
POSITION (for stems in other directions)false

delayIn seconds. If null the best delay is automatically chosen (depending on the showOn event).null

hideDelayIn seconds.0.1

fixedIf target is not null, elements are always fixed.false

showOnEvent name (eg: 'mouseover'), or 'creation' if you want it to show when the tooltip is created. Null if you want no event.'mouseover'

hideTriggerWhich element should trigger the hiding process.
Possible values are: 'trigger', 'tip', 'target', 'closeButton', ELEMENT, or null'trigger'

hideOnEvent name. (eg: 'click'). If false Opentip decides which event is best ('click' for closeButton, 'mouseout' if not).null

offsetDefined like this: [ xInteger, yInteger ].[ 0, 0 ]

autoOffsetIf set to true, offsets are calculated automatically to position the tooltip. (pixels are added if there are stems for example)true

containInViewportIf set to true, opentips that would appear offscreen are repositioned inside the browser viewport. targetJoints, tipJoints and stems are also repositioned.true

showEffectThe string of the scriptaculous effect you would call as a function on the object.'appear'

fallbackShowEffectIf the browser has to use scriptaculous, and the showEffect does not exist, this effect will be set as showEffect instead.'appear'

hideEffectThe same as show effect'fade'

fallbackHideEffectThe same as fallback show effect'fade'

showEffectDurationExpressed in seconds0.3

hideEffectDurationExpressed in seconds0.2

stemSizeAn integer defining the stem size in pixels.8

tipJointThis is a POSITION.
The tip joint defines which part of the tooltip is the "pointer".[ 'left', 'top' ]

targetIf null, no target.
If true: the trigger element is the target.
Otherwise pass an ELEMENT.null

targetJointThis is a POSITION.
The target joint defines where the tooltip points to. If set to null, it's the opposite of tipJoint.null

ajaxAn object formed like this:
{ url: 'address', options: { AJAXoptions } }
For more information on Ajax tips see the examples section.false

groupSimply pass a string as the group name (eg: 'login'), and all visible tooltips in this group will be hidden when a tooltip in this group is shown.null

escapeHtmlIf true, the passed content will be html escaped.false

As you see you can decide when the tooltip disappears by selecting a hideOn event.
But you can also easily define your own close buttons. In fact, as soon as opentip finds an element with the class 'close' it observes this element as close button.
So just add this to your content (this also works with Ajax):

<button class="close">Click me to close</button>

// or 

<a href="javascript:undefined;" class="close">Click me to close</a>

Styles

Styles are an easy way to setup your opentips without having to pass the options every time you want an opentip to appear.
Styles are a way to group options, and reuse them.
The styles we offer differ mainly in the design, but styling can be much more useful!

Opentip.styles.myNewStyle = {

  className: 'slick',

  stem: true,

  stemSize: 12,

  target: true,

  showEffect: null

};

$('myElement').addTip('Just testing.', { style: 'myNewStyle' });

If you want all your opentips to use a certain style, you can define it like this:

Opentip.defaultStyle = 'rounded';

Examples

Ajax

Simple Ajax example that loads the content that contains a close button:

$('elementId').addTip({

  showOn: 'click',

  ajax: { url: 'ajaxcontent.html' },

  hideTrigger: null,

  fixed: true

});

// Ajax returns:
// The content loaded successfully!<br />
// <button class="close">Click me to close</button>

Ajax link

This is even easier: transform a link into an Ajax opentip with one line:

<a href="ajaxDemo.php"
   onclick="javascript:Tips.add(this, event, { ajax: true });">
      Click me to load Ajax</a>

Click me to load Ajax

Note that this creates valid links that point to your resource, so search engines can index those resources.
When an opentip is added to a link and the ajax option is set, but no url is given, Opentip automatically uses the href attribute of the link as Ajax url. If you want to pass additional parameters to the ajax call, just use:

Tips.add(this, event, { ajax: { options: [...] } });

Forms

Opentip is quite useful to manage forms too.
This example shows how you would notify a user an input field is not correct.
In this case username can't be empty, and the notification only disappears when the user changes the input.


<form id="myForm" action="javascript:undefined">
  Username<br />
  <input name="username" type="text" value="" /><br />
  <input type="submit" value="Submit" />
</form>

<script type="text/javascript">
  $("myForm").observe("submit", function() {
    if (!this.username.present()) {

      $(this.username).addTip("This can't be empty", {
        target: true,
        stem: true,
        tipJoint: [ "left", "middle" ],
        showOn: "creation",
        hideOn: "change"
      });

    }
    return undefined;
  });
</script>

And here what it looks like:

Groups

Sometimes you want to group tooltips, so only one is shown at a time.

<script type="text/javascript">
  Opentip.styles.grouped = {
    group: 'login',
    hideOn: 'click',
    target: true,
    stem: true,
    tipJoint: [ 'center', 'top' ]
  }
</script>

<a href="javascript:undefined;"
   onclick="javascript:Tips.add(this, event, 'Login!',
      { style: 'grouped' });">Vote</a>

<a href="javascript:undefined;"
   onclick="javascript:Tips.add(this, event, 'Login!',
      { style: 'grouped' });">Comment</a>

This results in:

Vote Comment

Advanced

There are a view more useful properties of the opentip class, that are not needed that often, but are quite useful.

Debugging with Firebug or Safari

To set the opentip class to debuggin mode, just set Opentip.debugging = true; after including the opentip.js file.
If you have Firebug or Safari in developer mode, opentip will then output some debugging information.

Multiple Ajax links

This example is something I found useful in some situations.
Apply Opentip to multiple elements, to transform links to ajax requests.

<div id="links">
  <a href="ajaxcontent.html">Link A</a>
  <a href="ajaxcontent.html">Link B</a>
  <a href="ajaxcontent.html">Link C</a>
</div>
<script type="text/javascript">
  $("links").select("a").invoke("addTip", { showOn: "click", ajax: true });
</script>

The result:

Link A Link B Link C

Setting content as function

This avoids unnecessary element creation at the creation of a tooltip.
If the content is set as a function, this function will be called when the tooltip is first shown, and the result is used as content.
Example:

var myObject = {
  buildTooltipElements: function(tip) {
    return Builder.node(
      'div',
      'This is the content of tooltip #' + tip.id
    );
  },
  setupTooltip: function() {
    $('someElement).addTip(this.buildTooltipElements);
    // Don't forget to use .bind(this) if necessary.
  }
};

Additional information

To prevent surprises, and to fully list all of opentip features, here is some additional information about the opentip class:

Opentip automatically focuses the first input/textarea found in the content when shown.
When you call .hide() on a tip manually, you can pass along the afterFinish parameter, which is a function that will be called after the hideEffect has finished.
Opentips get repositioned when the browser gets resized.
YES! Some of the stuff is based on CSS3. But only the eye candy stuff, like rounded corners and box shadows.
If you can't live with that... well contact me. If I have a good day I'll implement some workarounds.

Download Opentip1.4.2Jan, 17 2012