documentation

To programmatically instantiate an Opentip you use this syntax:

new Opentip("#my-trigger-element", "Optional content", "Optional title", { ...options... })

The content and title are optional but it doesn’t make much sense to omit the content unless the content gets downloaded with AJAX.

Alternatively you can use html attributes to create opentips:

html attributes

When the document is loaded Opentip scans the document and finds all elements with a data-ot attribute, and instantiates an Opentip automatically. To configure the Opentip this way simply add attributes beginning with data-ot- and the dashed option name. Example:

<div data-ot="The content" data-ot-delay="2" data-ot-hide-trigger="closeButton">Hover me</div>

opentip object api

You can manage Opentips with a few methods after you created them.

var myOpentip = new Opentip($("#element"));

myOpentip.show(); // Shows the tooltip immediately
myOpentip.hide(); // Hides the tooltip immediately
myOpentip.prepareToShow(); // Shows the tooltip after the given delays. This could get interrupted
myOpentip.prepareToHide(); // ...

myOpentip.deactivate();
myOpentip.activate();

myOpentip.setContent("New content"); // Updates Opentips content

targeting

By default Opentips «target» the mouse cursor, which means they follow the mouse. If you want the Opentip to be fixed, you could do so by setting the fixed: true option, but that would still make the Opentip appear at the cursor position.

To tell an Opentip that you want it to point to an element, you can set the target:

// This will create an Opentip pointing to the top center of #target-element
new Opentip("#trigger-element", { target: "#target-element", tipJoint: "bottom" });

(This automatically sets the fixed option to true)

Since most of the time your target element will be the trigger element, you can just set: target: true.

creating styles

Styles are a way to store predefined settings. So instead of setting the color, and stemsize, etc… on every Opentip you create, you can just create one style and reuse it in all of your Opentips.

You can define everything in a style that you could define in the opions object. So if, for example, all your error tooltips should look like the built in alert theme, should be fixed, have a stem and should be shown on creation you could create the style like this:

Opentip.styles.myErrorStyle = {
  // Make it look like the alert style. If you omit this, it will default to "standard"
  extends: "alert",
  // Tells the tooltip to be fixed and be attached to the trigger, which is the default target
  target: true,
  stem: true,
  showOn: "creation"
};

// Then use it like this:
myTip = new Opentip(triggerElement, "Content", { style: "myErrorStyle" });

Side note: The options object you pass when creating an Opentip is actually just an ad hoc style created only for this one specific tooltip. The options style and extends are actually exactly the same. So you could theoratically create an Opentip like this: new Opentip("Content", { extends: "myErrorStyle" }); although I feel that style is better suited in that case.

You can also set a default style that all Opentips that don’t specify a specific style option will use like this:

Opentip.defaultStyle = "myAwesomeStyle"; // The default is "standard"

grouping opentips

Sometimes you want to hide other Opentips when showing one.

For example: you could have a list of tags and when the user clicks one you show some additional tag information. But you also want to hide all other tag informations so to make sure that only one Tag-Opentip is visible at all times.

This is done through grouping:

<a href="/tag-info/tag/1" data-ot="Tag info 1" data-ot-group="tags" data-ot-ajax="true">Tag 1</a>
<a href="/tag-info/tag/2" data-ot="Tag info 2" data-ot-group="tags" data-ot-ajax="true">Tag 2</a>
<a href="/tag-info/tag/3" data-ot="Tag info 3" data-ot-group="tags" data-ot-ajax="true">Tag 3</a>

Note: This example is not the best way to solve such problems. Look at the “Best practices” section below for a better way to handle it.

programmatically managing opentips

One of the most common questions asked is how to hide Opentips or disable them.

Most problems arise because often Opentips are created with HTML data- attributes although it makes more sense to create them programmatically.

Here’s an example of how you would manage an Opentip in your application with jQuery:

$(function() {
  // Start when document loaded
  var myInput = $("#my-input");
  var inputOpentip = new Opentip(myInput, { showOn: null, style: 'alert' });

  // Hide the tooltip on focus so we don't bother the user while editing.
  myInput.focus(function() { inputOpentip.hide(); });
  myInput.change(function() {
    if (myInput.val()) {
      // Everything fine
      inputOpentip.hide();
    }
    else {
      // Oh oh
      inputOpentip.setContent("Please fill out this field.");
      inputOpentip.show();
    }
  });

});

If for some reason you can’t or don’t want to create Opentips programmatically but still want to access them, there’s good news! You can.

Every Opentip created is stored on the element itself in an opentips array. To access it, you can use the functions provided by your framework to access arbitrary data of HTML elements.

  // jQuery
  $("#my-element").data("opentips"); // Returns a list of Opentips associated with this element
  // Prototype
  $("my-element").retrieve("opentips");
  // Ender
  $("#my-element").data("opentips");

show / hide all opentips

Sometimes you just want to show or hide all Opentips on the page. To do so, Opentip keeps a list for you: Opentip.tips.

So, to hide all tips, just do:

  for(var i = 0; i < Opentip.tips.length; i ++) { Opentip.tips[i].hide(); }

best practices

You should avoid abusing the HTML configuration. If you mainly have a static HTML site and you want to add Opentips here and there, it’s fine (but even then, try not to put to much configuration in the HTML attributes, but rather create a new style that you can use – especially if you notice that your configuration is repeated a lot).

As soon as you need interaction with your Opentips, it’s probably a good idea to create them programmatically. The same goes for many Opentips that need to be created and would result in lots of repeating HTML code.

Let’s say you have a list of tags, and you want to show information about them when clicked. The best way to approach that would be to create the HTML elements without a notion about Opentips like this:

<div id="tags">
  <a href="/tag-info/1" class="tag">Tag 1</a>
  <a href="/tag-info/2" class="tag">Tag 2</a>
  <a href="/tag-info/3" class="tag">Tag 3</a>
  etc...
</div>

To attach the Opentips then, you would do so like that in JS (with jQuery):

// Create a style for all tag Opentips
Opentip.styles.tag = {
  ajax: true, // The URL to download will be taken from the href attribute
  showOn: 'click', // this will disable the default <a /> link behaviour.
  target: true, // Takes the <a /> element as target
  tipJoint: "bottom", // So the tooltip floats above the link
  group: "tags" // Ensures that only one tag Opentip is visible
};

// Now create an Opentip for each tag element
$("#tags a.tag").each(function(tagElement) {
  new Opentip(tagElement, { style: "tag" });
});

options

Glossary

• JOINT
  Defines a position inside an Opentip. This is a case insensitive string with a horizontal position (left, center, right) and a vertical position (top, middle, bottom) in any order where center and middle can be omited.

  

• OFFSET
  An array with x and y position as contents.

  Example: [ 100, 50 ]