DEPRECATED AS OF 2.1

The AJAX plugin was deprecated in qTip 2.1. Please use jQuery Deferred Objects as your content.text instead. A full explanation and guide is available in the Content Guide.

Overview

The AJAX plugin extends your content options allowing you to use jQuery's built-in AJAX functionality to retrieve remote content. This is especially useful in conjunction with the Modal plugin to create modal dialogues with minimal effort, such as login forms.

Basics

Let's start off with the basic AJAX object, which is used by qTip for AJAX functionality:

$('.selector').qtip({
    content: {
        text: 'Loading...', // The text to use whilst the AJAX request is loading
        ajax: {
            url: '/path/to/file', // URL to the local file
            type: 'GET', // POST or GET
            data: {} // Data to pass along with your request
        }
    }
});

What you see above is the very basic setup for an AJAX call using qTip. The AJAX object itself is simply an embedded version of the same object used in the original jQuery.ajax call.

qTip²  will automatically take the response from the request and set the content.text for you if you don't override the default success handler. However, if you intend on using your own success callback, you'll need to set it yourself using the set method i.e.

$('.selector').qtip({
    content: {
        text: 'Loading...', // The text to use whilst the AJAX request is loading
        ajax: {
            url: '/path/to/file', // URL to the local file
            type: 'GET', // POST or GET
            data: {}, // Data to pass along with your request
            success: function(data, status) {
                // Process the data

                // Set the content manually (required!)
                this.set('content.text', data);
            }
        }
    }
});

Note: Access to the API inside $.ajax callbacks is achieved via the 'this' variable e.g. this.set(), as opposed to it being passed as an argument like in the API events.

Note: If you wish to simply filter the returned content before it gets set as the content, use the dataFilter callback.

HTML

The default. All you have to do is supply the URL and request type, as well as any data you need to send along with the request, and the returned data automatically replaces the tooltip contents. If an error occurs during the response, the tooltip contents are replaced with a description of the error that occurred.

Using a selector to grab particular elements

Just like the jQuery.load method you can specify a custom selector after the URL, delimited by a space, in order to only return a particular sub-set of elements from the page!. For example:

url: 'myCustomPage.html a' // Return all <a> elements of the URL's HTML
url: 'myCustomPage2.html #table5' // Return the element with an ID of 'table5'

JSON

Nowadays the preferred method to return data from an AJAX request is via JSON, or JavaScript Object Notation. This is basically a fancy way of saying a JavaScript object.

Many popular server-side languages such as Ruby and PHP provide ways of encoding their native data structures into JSON syntax. Once you have your JSON being spat out correctly (example below), take a look at how to retrieve and use the JSON using qTip:

/* JSON string returned by the server */
{
    "person": {
        "firstName": "Craig",
        "lastName": "Thompson",
        "gender": "Male",
        "dob": "14/09/19??",
        "country": "United Kingdom"
    },
    "job": {
        "title": "Web Developer",
        "company": "craigsworks",
        "since": 2007
    },
    "specialities": [
        "JavaScript", "jQuery", "CSS",
        "(X)HTML", "PHP", "MySQL"
    ]
}

/* qTip2 call below will grab this JSON and use the firstName as the content */
$('.selector').qtip({
    content: {
        text: 'Loading...', // Loading text...
        ajax: {
            url: '/path/to/file', // URL to the JSON script
            type: 'GET', // POST or GET
            data: { id: 3 }, // Data to pass along with your request
            dataType: 'json', // Tell it we're retrieving JSON
            success: function(data, status) {
                /* Process the retrieved JSON object
                * Retrieve a specific attribute from our parsed
                * JSON string and set the tooltip content.
                */
                var content = 'My name is ' + data.person.firstName;

                // Now we set the content manually (required!)
                this.set('content.text', content);
            }
        }
    }
});

As you can see, processing the data is very simple. We take the parsed JSON string returned from the server, use its attributes to create the new content of the tooltip, and call the API's set method to replace the tooltip contents with it. Easy peasy!

Note: Unfortunately, the dataFilter callback cannot be used to filter the JSON object like in the HTML example above, only the unparsed JSON string.

content.ajax

Values

{ Object }, false (Default: false)

Overview

This option allows you specify a regular jQuery.ajax object. This object is used in the $.ajax method and the retrieved content is used for the tooltips content.

Examples

Let's grab some simple HTML content from a file as our tooltip contents:

$('.selector').qtip({
    content: {
        ajax: {
            url: 'tooltipContent.html'
        }
    }
});

We can also use the content.text to specify a loading image whilst we wait for the AJAX request to complete:

$('.selector').qtip({
    content: {
        text: '<img src="images/loading.gif" alt="Loading..." />',
        ajax: {
            url: 'tooltipContent.html'
        }
    }
});

See also

• content.text

Notes

• Before the AJAX content loads, regular content.text/attr options are used for the tooltip content.

content.ajax.once

Values

true, false (Default: true)

Overview

Allows you specify whether or not the AJAX content is retrieved each time the tooltip is shown or just once when rendered.

Examples

Perhaps we want to retrieve some frequently updated details about member each time the tooltip is shown:

$('.selector').qtip({
    content: {
        ajax: {
            url: 'members.php',
            data: { id: 4 },
            once: false // Re-fetch the content each time I'm shown
        }
    }
});

Notes

• This option an extension of the regular jQuery.ajax object and is not a core jQuery.ajax option. It will only work with qTip² !

content.ajax.loading

Values

true, false (Default: true)

Overview

This option allows you whether or not the tooltip will be shown whilst content is being loaded via AJAX i.e. whether or not it is visible before the content is loaded.

Examples

To hide the tooltip whilst the initial content is loaded, set it to false

$('.selector').qtip({
    content: {
        text: 'This text won\'t be shown!',
        ajax: {
            url: 'mycontent.html',
            loading: false
        }
    }
});

See also

• content.text

Notes

• Even though the content.text will not be used, it must be set to something valid i.e. non-blank, so that the qTip will be considered valid and rendered.
• This option an extension of the regular jQuery.ajax object and is not a core jQuery.ajax option. It will only work with qTip² !

Elements

When the tip plugin is in use on a tooltip, a new element becomes available within the API elements object, which references the newly created tip:

$('.selector').qtip({
    content: {
        text: 'Tips plugin element'
    },
    events: {
        render: function(event, api) {
            // Grab the tip element
            var elem = api.elements.tip;
        }
    }
})

Styling

Styling the tip's background and border colours is done via CSS, not the options below. These are detected from the styles set on the qtip-tip element listed above. If no valid style can be found for the background or border colour properties, qTip will look for styles on specific elements, depending on what it's looking for:

border-color

• qtip-tip element
• qtip-titlebar element - If present and tip overlaps
• qtip-content element

background-color

• qtip-tip element
• qtip-titlebar element - If present and tip overlaps
• qtip-content element
• qtip element

If no valid style can be found on any of these elements, the initially detected style of the qtip-tip element will be used. A notable exception to the inheritance is the border property, which can be used to override the detected CSS border-width.

#000000 = Invalid style!

Since, by default, most browsers default to using pure black (rgb(0,0,0), #000 etc.) as the default colour, if qTip²  detects this it will look elsewhere for the styles as listed above. If you need to use pure black, the best work around is to use something very close to it visually, such as rgb(0,0,1) or #000001.

style.tip.corner

Values

true, "Corner", false (Default: true)

Overview

Defines where in relation to the tooltip the speech bubble tip is applied. Check-out the positioning docs for a full set of corner strings.

Examples

Let's create a regular qTip with a tip whose corner is inherited from the position.my option:

$('.selector').qtip({
    content: {
        text: 'I have a nice little callout pointer... nifty huh?'
    },
    style: {
        tip: {
            corner: true
        }
    }
});

We can also manually specify a different corner like so (if viewport adjustment is enabled, the tip position will not be adjusted):

$('.selector').qtip({
    content: {
        text: 'I have a nice little callout pointer... nifty huh?'
    },
    style: {
        tip: {
            corner: 'left center'
        }
    }
});

See also

• position.viewport
• position.my

Notes

• When set to true, the tip position will be inherited from the position.my property and adjusted automatically if viewport adjustment is enabled.
• The positioning values of 'center' and 'center center' are not valid positioning values in this plugin.

style.tip.mimic

Values

"Corner", false (Default: false)

Overview

Used in conjunction with style.tip.corner, this option overrides what corner type is rendered. Specifying a corner string here will cause the tip to render as this corner type, regardless of its position in relation to the tooltip.

You can also specify a single corner property e.g. "left" or "center", which will cause the tip to inherit its other properties from the corner string. This is primarily useful when using mimic with the position.viewport functionality.

Examples

Let's create a qTip with a similar tip style to ClueTip, whose tip arrow is equilateral and placed toward the top of the tooltip.

$('.selector').qtip({
    content: {
        text: 'I look very similar to a ClueTip tooltip in terms of my callout pointer.'
    },
    style: {
        tip: {
            corner: 'right top',
            mimic: 'right center'
        }
    }
});

As mentioned above, we can also use mimic with a single value too, to make for example the tip mimic 'center' and comply with viewport adjustment changes:

$('.selector').qtip({
    content: {
        text: 'My tip will mimic the center style regardless of position or viewport adjustment!'
    },
    position: {
        viewport: $(window) // Adjust position to keep within the window
    },
    style: {
        tip: {
            corner: 'right top',
            mimic: 'center' // Single 'center' value here
        }
    }
});

See also

• style.tip.corner

Notes

• This option overrides the presentation of the tip only. It does not effect the tips position!

style.tip.border

Values

true, Integer (Default: true)

Overview

This option determines the width of the border that surrounds the tip element, much like the CSS border-width property of regular elements. If a boolean true is passed, the border width will be detected automatically based on the border-width of the side the tip falls on. See the styling section for more information on this.

Examples

Let's create a qTip with a style to Google Maps tooltips, whose arrow blends with the border of the tooltip:

$('.selector').qtip({
    content: {
        text: 'I look very similar to a Google Maps tooltip!'
    },
    style: {
        classes: 'qtip-light',
        tip: {
            corner: 'bottom center',
            mimic: 'bottom left',
            border: 1,
            width: 88,
            height: 66
        }
    }
});

Notes

• Unlike qTip1 the tip border follows the normal CSS property and applies the border outside the element, not inside.
• See the styling section for more information on border-width detection

style.tip.width

Values

Integer (Default: 6)

Overview

Determines the width of the rendered tip in pixels, in relation to the side of the tooltip it lies upon i.e. when the tip position is on the left or right, this quantity actually refers to the tips height in visual terms, and vice versa.

Examples

Let's make a tooltip with an elongated tip width

$('.selector').qtip({
    content: {
        text: 'My callout pointer looks a bit wackier than usual'
    },
    style: {
        tip: {
            corner: true,
            width: 24
        }
    }
});

See also

• style.tip.height

Notes

• Make sure this is a number only, don't include any units e.g. 'px'!
• Prior to the 26th April 2012 nightly, this was an absolute value i.e. it determined the width of the tooltipin relation to the window. This was changed and you should update your code if you relied on this fact.

style.tip.height

Values

Integer (Default: 6)

Overview

Determines the height of the rendered tip in pixels, in relation to the side of the tooltip it lies upon i.e. when the tip position is on the left or right, this quantity actually refers to the tips width in visual terms, and vice versa.

Examples

Let's make a tooltip with an elongated tip height

$('.selector').qtip({
    content: {
        text: 'My callout pointer looks a bit wackier than usual'
    },
    style: {
        tip: {
            corner: true,
            height: 24
        }
    }
});

See also

• style.tip.width

Notes

• Make sure this is a number only, don't include any units e.g. 'px'!
• Prior to the 26th April 2012 nightly, this was an absolute value i.e. it determined the height of the tooltipin relation to the window. This was changed and you should update your code if you relied on this fact.

style.tip.offset

Values

Integer (Default: 0)

Overview

Determines the offset of the tip in relation to its current corner position.

Examples

Say your tooltip is positioned at the bottom left of your target, but you want the tip shifted slightly to left instead of flush with the side of the tooltip:

$('.selector').qtip({
    content: {
        text: 'My callout pointer looks a bit wackier than usual'
    },
    style: {
        tip: {
            corner: true,
            offset: 5 // Give it 5px offset from the side of the tooltip
        }
    }
});

See also

• style.tip.width
• style.tip.height

Notes

• This value is relative i.e. depending on which corner the tooltip is set it will behave differently.
• If your value is too large positioning problems can occur. Don't exceed a value equal to the height/width of the tooltip if possible.
• Negative values will only be applied to 'center' positioned tooltips e.g. top center, left center.

Elements

When the modal plugin is in use on a tooltip, a new element becomes available within the API elements object, which references the overlay element used to dim the page:

$('.selector').qtip({
    content: {
        text: 'Modal plugin element'
    },
    events: {
        render: function(event, api) {
            // Grab the overlay element
            var elem = api.elements.overlay;
        }
    }
})

z-index property

When a qTip utilises the modal plugin (by setting show.modal.on to true) a separate z-index is applied from that of normal, non-modal qTips to prevent overlapping issues. The default z-index of modal qTips is simply 200 less than that of regular non-modals:

$.fn.qtip.zindex = 15000; // Non-modal z-index
$.fn.qtip.modal_zindex = 14800; // Modal-specific z-index

When overriding the normal z-index property, be sure to change the modal-specific one too, but keep in mind you'll need to set it to a value lower than the non-modal property! Otherwise you'll run into funny problems with overlapping when using several different tooltips.

CSS

To dim the page, the modal plugin uses fullscreen div element. You can modify the colour and other attributes of the overlay in your jquery.qtip.css CSS file. Here's the default settings for the 'overlay' element:

#qtip-overlay{
    position: fixed;
    left: -10000em;
    top: -10000em;
}

    /* Applied to modals with show.modal.blur set to true */
    #qtip-overlay.blurs{ cursor: pointer; }

    /* Change opacity of overlay here */
    #qtip-overlay div{
        position: absolute;
        left: 0; top: 0;
        width: 100%; height: 100%;

        background-color: black;

        opacity: 0.7;
        filter:alpha(opacity=70);
        -ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=70)";
    }

If this isn't already present in your CSS file you'll need to add it manually.

Note: If you need to adjust the opacity of the overlay, change the inner div's properties, not the #qtip-overlay element.

$.fn.qtip.modal_zindex

Value

14800

Overview

Determines the base z-index of all modal qTips on the page of which no modal qTip z-index will drop below.

Examples

If you're using another plugin that happens to use a higher z-index than the default, increase it a little:

// Now your qTip's appear above the other plugin elements, yipeee!
$.fn.qtip.modal_zindex = 20000;

See also

• $.fn.qtip.zindex

Notes

• Try to make sure this value stays below that of the $.fn.qtip.zindex property to prevent rendering issues.
• Updating this option after you've already created some tooltips can have some pretty weird after-effects!

$.fn.qtip.plugins.modal.focusable

Value

['a[href]', 'area[href]', 'input', 'select', 'textarea', 'button', 'iframe', 'object', 'embed', '[tabindex]', '[contenteditable]']

Overview

An array of selectors used to determine which elements are considered "focusable" within the tooltip, for use with the stealfocus option.

See also

• modal.stealfocus

show.modal.on

Values

true, false (Default: false)

Overview

Determines whether or not the tooltip is 'modal' e.g. dims the rest of the page when shown.

Examples

Let's make a really quick login form that dims the rest of our page and is centered on screen

$('.selector').qtip({
    content: {
        text: $('#LoginForm')
    },
    position: {
        my: 'center',
        at: 'center',
        target: $(document.body)
    },
    show: {
        modal: {
            on: true
        }
    }
});

We can also use some shorthand notation instead:

$('.selector').qtip({
    content: {
        text: $('#LoginForm')
    },
    position: {
        my: 'center',
        at: 'center',
        target: $(document.body)
    },
    show: {
        modal: true // Omit the object and set it to true as short-hand
    }
});

See also

• Blanket CSS properties

Notes

• To dim the page a fullscreen translucent div is used, so all controls with a z-index lower than that of the blanket, as defined in your CSS file, will appear below and will be un-interactable whilst the blanket is visible.

show.modal.blur

Values

true, false (Default: true)

Overview

Determines whether or not clicking on the dimmed background of the page hides the tooltip and removes the dim. When enabled the overlay element has a 'blurs' class applied to it.

Examples

Let's modify our login tooltip so you can only hide the tooltip by clicking the title button or hitting escape:

$('.selector').qtip({
    content: {
        text: $('#LoginForm'),
        text: 'Login',
        button: true
    },
    position: {
        my: 'center',
        at: 'center',
        target: $(document.body)
    },
    show: {
        modal: {
            on: true,
            blur: false
        }
    }
});

See also

• Blanket CSS properties

Notes

• When enabled the overlay element has a 'blurs' class applied to it. See CSS section for more details.
• To dim the page a fullscreen translucent div is used, so all controls with a z-index lower than that of the blanket, as defined in your CSS file, will appear below and will be un-interactable whilst the blanket is visible.

show.modal.escape

Values

true, false (Default: true)

Overview

Determines whether or not hitting the escape key will hide the tooltip.

Examples

Let's modify our login tooltip so you can only hide it by clicking the title button:

$('.selector').qtip({
    content: {
        text: $('#LoginForm'),
        text: 'Login',
        button: true
    },
    position: {
        my: 'center',
        at: 'center',
        target: $(document.body)
    },
    show: {
        modal: {
            on: true,
            blur: false,
            escape: false
        }
    }
});

See also

• Blanket CSS properties

Notes

• You must have the window focused for the keyboard event to be detected properly

show.modal.stealfocus

Values

true, false (Default: true)

Overview

Determines whether or not users can focus inputs and elements outside of the tooltip when visible. Elements that gain focus outside the tooltip when this is enabled will be immediately blured and focus restored to the first focusable element within the tooltip.

Elements within the tooltip that are considered "focusable" are determined by the array of selectors in the $.fn.qtip.modal.focusable property.

See also

• $.fn.qtip.modal.focusable

show.modal.effect

Values

function() {}, true, false (Default: true)

Overview

Determines the type of effect that takes place when showing and hiding the modal overlay. A custom method can also be used whose scope is the overlay element when called. If set to false, no animation takes place. If set to true, a default a fadeIn animation takes place with a duration of 90ms.

Examples

Let's create a modal tooltip whos overlay fades in to a custom opacity

$('.selector').qtip({
    content: {
        text: 'I\'m a model tooltip with a custom overlay opacity'
    },
    show: {
        modal {
            on: true,
            effect: function(state) {
                /*
                    "state" determines if its hiding/showing
                    "this" refers to the overlay
                    0.4 and 0 are the show and hide opacities respectively.
                */
                $(this).fadeTo(90, state ? 0.4 : 0, function() {
                    if(!state) { $(this).hide(); }
                });
            }
        }
    }
});

Notes

• By default a fadeIn animation takes place with a duration of 90ms.

Position-dependant classes

When the position.adjust.method is set to either "flip" or "flipinvert" on one or both directions an appropriate class is applied to the qTip which denotes its current Corner position. The following list details the corner values along with their associated class:

• top left - qtip-pos-tl
• top center - qtip-pos-tc
• top right - qtip-pos-tr
• bottom left - qtip-pos-bl
• bottom center - qtip-pos-bc
• bottom right - qtip-pos-br
• left top - qtip-pos-lt
• left center - qtip-pos-lc
• left bottom - qtip-pos-lb
• right top - qtip-pos-rt
• right center - qtip-pos-rc
• right bottom - qtip-pos-rb
• center center - qtip-pos-c

You can use this to easily adjust the styling of your qTip's based upon their viewport position, cool huh? For example:

.myStyle.qtip-pos-tl{
    color: red;
}

This will cause all qTips with a class (see style.classes) of myStyle to have red text when it's top left corner is pointing at the position.target.

position.viewport

Values

jQuery([ ]), true, false (Default: false)

Overview

Determines the viewport used to keep the tooltip visible i.e. the element whose boundaries the tooltip must stay visible within at all times if possible. If true it's value will be inherited from the position.container property.

Examples

Make a tooltip that will attempt to stay within the window viewport, adjusting the positioning corners as needed:

$('.selector').qtip({
    content: {
        text: 'If I go off-screen, my positioning corners will adjust. Resize your browser window to see!'
    },
    position: {
        viewport: $(window)
    }
});

Notes

• Your position.my/at options will be temporarily adjusted when using this functionality.
• If set to true this value will be inherited from the position.container property.

position.adjust.method

Values

"{flip|flipinvert|shift|none} {flip|flipinvert|shift|none}" (Default: "flipinvert")

Overview

This option determines the kind of viewport positioning that takes place.

The default "flip" type basically flips the tooltip when it goes off-screen i.e. from top-right, to bottom-right etc. The "flipinvert" type works the same way, except when the flip happens it inverts the adjust.x and adjust.y properties. The "shift" type attempts to keep the tooltip on screen by adjusting only by the amount needed to keep it within the viewport boundaries.

You can specify the behaviour of each axis (i.e. horizontal and vertical) separately, for example a value of "flip none" will cause the tooltip to flip across the horizontal axis when it extends out the viewport, but do nothing when it extends out the viewport vertically. There are a number of combinations.

Examples

Instead of the default flip repositioning, let's use the shift repositioning, but only shift it horizontally

$('.selector').qtip({
    content: {
        text: 'My position is adjusted just enough to keep me within the viewport, but only along the x axis (horizontally)'
    },
    position: {
        adjust: {
            method: 'shift none'
        }
    }
});

Notes

• Supplying a single string such as "flip", "flipinvert" or "shift" will cause qTip²  to use that method for both axis'.
• This system is very similar to that used in the jQuery UI Position plugin.
• Both flip and shift methods also adjusts the tip position, if enabled.

See also

• position.viewport

Usage

This particular plugin requires no additional user configuration. In order to utilise it, simply make sure you have it included in your qTip build and make sure that you point your jQuery selector to the <area> elements, NOT the <map> element! For example:

$('area').qtip({
    content: {
        text: 'Support for area maps with no extra configuration! Awesome.'
    },
    position: {
        my: 'top left',
        at: 'bottom right'
    }
});

Usage

This particular plugin requires no additional user configuration. In order to utilise it, simply make sure you have it included in your qTip build and use as normal:

$('path').qtip({
    content: {
        text: 'Support for SVG with no extra configuration! Awesome.'
    },
    position: {
        my: 'top left',
        at: 'bottom right'
    }
});

Usage

This particular plugin requires no additional user configuration. In order to utilise it, simply make sure it's included in your qTip²  build.

Note that this is a compatability plugin for IE6 only, and will have no effect in any other browser.

Elements

In IE6 only, the created BGIframe element is available through the API's elements object:

$('.selector').qtip({
    content: {
        text: 'IE6 bgiframe plugin'
    },
    events: {
        render: function(event, api) {
            // Grab the BGIFrame element
            var elem = api.elements.bgiframe;
        }
    }
});