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.
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.
qTip2 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]../events.md).
Note: If you wish to simply filter the returned content before it gets set as the content, use the dataFilter callback.
Now that we know how to setup our basic AJAX call, let's look at the different types of data that can be returned, and how to deal with them. First up is the HTML content. This is the simplest of the lot, since the HTML is simply appended to the tooltip contents.
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.
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.
{ Object }, false (Default: false)
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.
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'
}
}
});- Before the AJAX content loads, regular content.text/attr options are used for the tooltip content.
true, false (Default: true)
Allows you specify whether or not the AJAX content is retrieved each time the tooltip is shown or just once when rendered.
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
}
}
});- This option an extension of the regular jQuery.ajax object and is not a core jQuery.ajax option. It will only work with qTip2!
true, false (Default: true)
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.
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
}
}
});- 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.