Events Guide - qTip2/qTip2 GitHub Wiki

Events

Multiple callbacks

Unlike the 1.x releases, qTip2 now supports multiple callbacks for your events, so you can have lots of things triggered from a single tooltip event. Let's dive in and look at an example:

$('.selector').qtip({
	content: 'Multiple callbacks... mmm...',
	events: {
		show: function(event, api) { $('.selector').addClass('show'); },
		render: function(event, api) {
			// Grab the tooltip element from the API
			var tooltip = api.elements.tooltip
 
			// ...and here's the extra event binds
			tooltip.bind('tooltipshow', function(event, api) {
				$('.selector').removeClass('active');
			})
		}
	}
});

You'll notice that we're actually using two event callbacks, show and render. The events.show option sets the first callback, and the render option lets us assign multiple other callbacks using a regular old .bind() method, once we know the tooltip has rendered.

You can also bind callbacks outside the qTip2 call, again using a regular bind. Though take note that this only works if pre-rendering is enabled, as you can only bind events to elements that you know exist in the DOM when it's bound. Here's the example:

$('.selector').qtip({
	id: 'multibind', // Give it an ID of 'qtip-multibind' for easy reference
	prerender: true, // Pre-render tooltip HTML on document.ready
	content: 'Multiple callbacks... mmm...',
	events: {
		show: function(event, api) {
			$('.selector').addClass('show');
		}
	}
});
 
// And here's our extra non-qTip-call bind, using our assigned class as a selector
$('#qtip-multibind').bind('tooltipshow', function() {
	$('.selector').removeClass('active');
});

Stopping events

Stopping the event before its outcome occurs… possible? Sure! Just like regular events assigned using .bind() or .delegate(), using the event.preventDefault() method will cause the event to be stopped e.g. not proceed or 'bubble'. This is similar to the old 1.x before callbacks. Example:

$('.selector').qtip({
	content: 'Multiple callbacks... mmm...',
	events: {
		show: function(event, api) {
			// Only show the tooltip if say... an element is also visible
			if($('.selector').is(':hidden')) {
				// IE might throw an error calling preventDefault(), so use a try/catch block.
				try { event.preventDefault(); } catch(e) {}
			}
		}
	}
});

Right-clicks

Now that we know how to stop events, we can pull off some pretty nice implementations. Like what you ask? Oh I don't know... maybe our own context menu?

$('.selector').qtip({
	content: $('#contextMenu'), // Use a pre-formatted element for the content
	position: {
		target: 'mouse', // Position it where the click was...
		adjust: { mouse: false } // ...but don't follow the mouse
	},
	show: 'mousedown', // Can't use click event for this, sorry!
	events: {
		show: function(event, api) {
			/*
			 * event.originalEvent contains the event that caused the callback to be fired.
			 * event.originalEvent.button tells us which button was clicked e.g. 1= left, 2 = right;
			 */
			if(event.originalEvent.button !== 2) {
				// IE might throw an error calling preventDefault(), so use a try/catch block.
				try { event.preventDefault(); } catch(e) {}
			}
		}
	}
})
// Little snippet that stops the regular right-click menu from appearing
.bind('contextmenu', function(){ return false; });

Now you've seen qTip2 isn't just limited to creating regular old tooltips, but can be used in some pretty interesting ways. The worlds your oyster… so go out and play! But make sure to write about it when you make something cool, and tell us where!

Delegation .on() / live() / .delegate()

There are plenty of tooltip scripts out there that support jQuery's new to 1.4 .live() / .delegate() / .on… so why should qTip2 be any exception? Well thankfully for you it isn't! To understand how to use these special event delegation techniques, it's best to simply dive into a code example and explain exactly what's happening:

// We'll encapsulate our .qtip() call in your .on() handler method
$(document).on('mouseover', '.selector', function(event) {
	// Bind the qTip within the event handler
	$(this).qtip({
		overwrite: false, // Make sure the tooltip won't be overridden once created
		content: 'I get bound to all my selector elements, past, present and future!',
		show: {
			event: event.type, // Use the same show event as the one that triggered the event handler
			ready: true // Show the tooltip as soon as it's bound, vital so it shows up the first time you hover!
		}
	}, event); // Pass through our original event to qTip
})
 
// Store our title attribute in 'oldtitle' attribute instead
.each(function(i) {
	$.attr(this, 'oldtitle', $.attr(this, 'title'));
	this.removeAttribute('title');
});

Ok so let's break down the code in its constituent parts...

Event handler

$(document).on('mouseover', '.selector', function(event) { });

This part tells jQuery to run the defined function on all elements matched by the .selector string, past present and future! This allows us to easily add tooltips to certain elements on a page, even when updating the DOM and adding new elements.

.qtip call

Now we have the .qtip() method being called via our .on() handler, let's take a look at the options required for this to work:

$(this).qtip({
	overwrite: false, // Make sure the tooltip won't be overridden once created
	content: 'I get bound to all my selector elements, past, present and future!',
	show: {
		event: event.type, // Use the same show event as triggered event handler
		ready: true // Show the tooltip immediately upon creation
	}
}, event); // Pass through our live event to qTip

To make sure our tooltips aren't re-created when the DOM is updated, we make sure our overwrite option is set to false. This is especially vital when using the $.ajax functionality. Next we setup our show.event to use the same event.type as the original .on() handler. This isn't required, but it's shorter than writing out our 'mouseover' string twice, and it minifies better!

Also, show.ready option should be true, which causes the tooltip to render and show as soon as the .qtip() method is called. This is vital, as otherwise the qTip will only show up on subsequent event triggers, not the initial one! Also, remember to pass the event object as the second .qtip() parameter, otherwise certain positioning stuff won't work as expected!

Remove title

Finally, we remove the title attribute and store it in the oldtitle attribute, so we don't get any of the default browser tooltips showing up.

// Store our title attribute in 'oldtitle' attribute instead
.each(function(i) {
    $.attr(this, 'oldtitle', $.attr(this, 'title'));
    this.removeAttribute('title');
});
⚠️ **GitHub.com Fallback** ⚠️