Hello! My name's , I'm using qTip at http:// and I think it's !

Note: Points will be deducted for bad grammar and spelling... and sentences that make no sense!

Advanced

Override defaults

Sometimes its easier to simply change the default tooltip settings than supplying the same options over and over again on the same page. And thankfully for you, it's pretty damn easy to change them. Enter the $.fn.qtip.defaults object:

// Define configuration defaults
$.fn.qtip.defaults = {
	prerender: false,
	id: false,
	overwrite: true,
	content: {
		text: true,
		attr: 'title',
		title: {
			text: false,
			button: false
		}
	},
	position: {
		my: 'top left',
		at: 'bottom right',
		target: false,
		container: false,
		viewport: false,
		adjust: {
			x: 0, y: 0,
			mouse: true,
			resize: true
		},
		effect: true
	},
	show: {
		target: false,
		event: 'mouseenter',
		effect: true,
		delay: 90,
		solo: false,
		ready: false,
		modal: false
	},
	hide: {
		target: false,
		event: 'mouseleave',
		effect: true,
		delay: 0,
		fixed: false,
		inactive: false
	},
	style: {
		classes: '',
		widget: false,
		tip: {
			corner: true,
			mimic: false,
			width: 8,
			height: 8,
			border: true,
			offset: 0
		}
	},
	events: {
		render: null,
		move: null,
		show: null,
		hide: null,
		toggle: null,
		focus: null,
		blur: null
	}
};

You can change these options one by one:

$.fn.qtip.defaults.content.text = 'I\'m here by default... woooooo!'; // Change the default tooltip text
$.fn.qtip.defaults.position.target = $('.selector');

…or if you plan on changing a large number of them you can once again use the magic of $.extend:

$.fn.qtip.defaults = $.extend(true, {}, $.fn.qtip.defaults, {
	content: {
		text: 'I\'m here by default... woooooo!' // Change the default tooltip text
	},
	position: {
		target: $('.selector') // Set an alternative positioning element
	}
});

NB You cannot use short-hand notation for this, you must specify all options in longhand. Otherwise you'll mess up the library logic... you lunatic!

Back to the top

Multiple tooltips per element

Sometimes you'll come across a use-case for multiple tooltips per-element, but since the qTip library normally doesn't allow this it can be hard to implement. Thankfully, once we know a bit about where the API is stored we can override this functionality and use multiple tooltips per element, much like was available in the 1.0 releases.

We know from the API documentation that the API for a tooltip is tored not only within the $.data of the tooltip element, but of the target element as well:

var api = elementWithqTip.data('qtip'); // Access the API of an element with a qTip applied

Since the tooltip itself applies this data simply to enforce the "one tooltip per-element" rule, we can delete it without any significant side-effects. This will allow us to apply multiple tooltips to this element, as long as we delete the data every time we create our tooltip:

// Create our first tooltip
$('.selector').qtip({
	content: 'I\'m just one of many tooltips that will render on this element...',
	position: {
		my: 'top left', at: 'bottom right'
	}
})
 
// Remove the previous tooltips data
.removeData('qtip')
 
// Create our second tooltip
.qtip({
	content: 'I\'m just one of many tooltips that will render on this element...',
	style: {
		classes: 'ui-tooltip-blue'
	}
});
Back to the top

Use with other plugins

Since qTip probably won't be the only jQuery (or other library) plugin on your page, it's pretty important to know how to use qTip along with them.

qTip uses a method known as "lazy-loading", which basically means that it only creates your tooltips on demand, not on page load (unless you tell it to). This means that you can't simply create your tooltip then use another plugin on its contents. You'll need to nest your other plugin(s) which utilise the tooltip contents, within the render event callback:

$('.selector').qtip({
	content: $('.selector') // The content you are putting in your tooltip, with the other plugin needs access to,
	events: {
		render: function() {
			// Grab the content
			var content = api.elements.content;
 
			// Now that the tooltip is rendered, we can call our other plugins to act on its contents
			$(content).otherPlugin();
		}
	}
})

OK so that deals with plugins that use content within a tooltip, but what about tooltips which use content within another plugin? I can't give exact details, because every plugin provides (or should anyway!) different callbacks, but basically you'll normally need to find an equivalent to qTip's render callback, and nest your qTip call within it.

Here's some examples of basic integration with some popular jQuery plugins:

/* jQuery Validation
 * http://bassistance.de/jquery-plugins/jquery-plugin-validation/
 */
$('form').validate({
	errorPlacement: function(error, element) {
		// qTip call
		$(element).not('.valid').qtip();
	},
	success: function(error) {
		// Hide tooltips on valid elements
		setTimeout(function() {
			myForm.find('.valid').qtip('hide');
		}, 1);
	}
})
 
/* FullCalendar
 * http://arshaw.com/fullcalendar/
 */
$('#calendar').fullCalendar({
	viewDisplay: function() {
		// qTip call
		$('.fc-event', this).qtip();
	}
});
 
/* jMonthCalendar
 * http://www.bytecyclist.com/projects/jmonthcalendar/
 */
$.jMonthCalendar.Initialize(
{
	onEventBlockClick: function(event)
	{
		// qTip call
		$(this).qtip();
	}
}
, events);

Of course these are just examples, a lot of the time you'll need your thinking caps on with the documentation to make sure you can fully integrate qTip with other plugins. If you need assistance, make sure to checkout the support forums! You never know... it might have been done already.

Back to the top

Wordpress integration

If you're using Wordpress, qTip needs some special loving to get it working nicely on your blog.

First off, Wordpress currently includes jQuery 1.3.2, which is no longer supported in qTip 2.x. You'll need to include tell Wordpress to use the latest jQuery script instead (1.4.2 as of this writing). This handy snippet updates Wordpress's jquery script to the newest possible version:

<?php// Source: http://www.wprecipes.com/how-to-use-jquery-1-4-by-default-on-your-wordpress-blog
if(!is_admin()){
	wp_deregister_script('jquery');
	wp_register_script('jquery', ("http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"), false, '');
}?>

Then, you'll need to use Wordpress's wp_enqeueue_script function to load qTip into your blog. Load up your current theme's file and locate your wp_head call. Insert this before it:

<?php// Source: http://digwp.com/2009/06/including-jquery-in-wordpress-the-right-way/
wp_enqueue_script('qtip', 'path/to/jquery.qtip-2.0.0.pack.js', array('jquery'), false, true); ?>

And wall-ah! qTip and jQuery are now included properly on your blog, in the footer on the page template. I also recommend you include another script which contains your qTip call:

<?php wp_enqueue_script('qtipCall', 'path/to/qtipcall.js', array('jquery', 'qtip'), false, true); ?>

NB More a more in depth step-by-step check-out this support forum post by newbie2012

NB If you're having problems, make sure to checkout the support forums for assistance.

Back to the top

Step-by-step tooltips

On your travels around the inter-webs, you've probably come across some websites that offer step-by-step guides to using their products. Most of them work by drawing you attention to specific elements on the page and explaining what they do, guiding you through step-by-step with next/prev links.

qTip is ideal for this sort of thing, so let's see exactly how we can implement this with a working example and it's code:

/* Important part - our steps. 
*    This contains an array of objects, each containing the properties of
*   the tooltip for each step. For this example we use only:
*
*      position.target    content.text       content.title
*   
*   You can obviously expand this as you require, but be sure to update the
*   custom event code to set the new properties if you do!
*/
var steps = [
	{ target: $('#target1'), title: 'Welcome to step 1!', content: 'Description...' },
	{ target: $('#target2'), title: 'Step 2...', content: 'We are...' },
	{ target: $('#target3'), title: 'and now Step 3', content: 'More text...' }
];
 
$(document).ready(function()
{
	$(document.body).qtip({
		id: 'step', // Give it an ID of ui-tooltip-step so we an identify it easily
		content: {
			text: steps[0].content, // Use first steps content...
			title: {
				text: steps[0].title, // ...and title
				button: true
			}
		},
		position: {
			my: 'top center',
			at: 'bottom center',
			target: steps[0].target, // Also use first steps position target...
			viewport: $(window) // ...and make sure it stays on-screen if possible
		},
		show: {
			event: false, // Only show when show() is called manually
			ready: true // Also show on page load
		},
		hide: false, // Don't' hide unless we call hide()
		events: {
			render: function(event, api) {
				// Grab tooltip element
				var tooltip = api.elements.tooltip;
 
				// Track the current step in the API
				api.step = 0;
 
				// Bind custom custom events we can fire to step forward/back
				tooltip.bind('next prev', function(event) {
					// Increase/decrease step depending on the event fired
					api.step += event.type === 'next' ? 1 : -1;
					api.step = Math.max(0, api.step);
 
					// Set new step properties
					var current = steps[api.step];
					if(current) {
						api.set('content.text', current.content);
						api.set('content.title.text', current.title);
						api.set('position.target', current.target);
					}
 
					// If we get to the end of the guide, hide the tooltip
					else if(api.step > steps.length - 1){
						api.hide();
					}
				});
			},
 
			// Destroy the tooltip after it hides as its no longer needed
			hide: function(event, api) { api.destroy(); }
		}
	});
});

OK, so we've got our step's array setup as well as our tooltip, now we need to add some next/prev links somewhere and add some JS magic:

<div id="next">Next step »</div>
<div id="prev">Previous step «</div>
$('#next, #prev').bind('click', function(event) {
	// Trigger the tooltip event
	$('#ui-tooltip-step').triggerHandler(this.id);
 
	// Stop the link from actually clicking
	event.preventDefault();
});
Back to the top