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!
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' } });
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.
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.
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:
$('#next, #prev').bind('click', function(event) { // Trigger the tooltip event $('#ui-tooltip-step').triggerHandler(this.id); // Stop the link from actually clicking event.preventDefault(); });
