[jQuery 1.5]

Les fonctions et les méthodes AJAX permettent d'échanger des données avec un serveur sans que le navigateur déclenche un rafraîchissement de la page web.

En raison de restrictions de sécurité imposées par Cross-Origin Resource SharingCross-Origin Resource Sharing, les transactions AJAX sont soumises à la politique de même origine, la requête AJAX ne parvient pas à récupérer les données d'un autre domaine, d'un sous domaine, ou d'un autre protocole. Seules les transactions AJAX manipulant des scripts et du JSONP ne sont pas soumises à ces restrictions.

Les méthodes $.get(), $.post(), $.getJSON(), $.getScript() et $(selector).load(), dont nous parlerons en dernier à cause de ses particularités, exécutent la majorité des transactions AJAX dont vous aurez besoin.

Toutes ces méthodes AJAX (sauf load) retournent un objet jqXHR qui implémente l'interface Promise.

Définitions :

jqXHR : l'objet jqXHR implémente l'interface Promise. Cet objet contient les propriétés, méthodes et comportements d'une promesse et il permet d'enchaîner les fonctions de rappel (callback) "success", "error" et "complete".

url : une chaîne de caractères contenant l'adresse web vers laquelle la demande est envoyée.

yourData : un objet (map) ou une chaîne de caractères contenant vos données à envoyer au serveur avec la requête AJAX.

Exemples et méthodes disponibles :

• { name: "John", time: "2pm" } ;
• { 'choices[]': ["Jon", "Susan"]} ;
• $(selector).serializeArray()$(selector).serializeArray() : encode un ensemble d'éléments sous forme d'un tableau de paires "key/value" ;
• $(selector).serialize()$(selector).serialize() : encode un ensemble d'éléments comme une chaîne de caractères ;
• $.param(obj)$.param(obj) : crée une représentation sérialisée d'un tableau ou d'un objet.

dataReceived : les données retournées par le serveur. Suivant les méthodes, ces données ont déjà subi le traitement approprié.

dataType : le type de données qui doivent être retournées par le serveur. Par exemple : "xml", "html", "text".

textStatus : une chaîne de caractères contenant le statut de la requête : "success", "notmodified", "error", "timeout", "abort", ou "parsererror".

errorThrown : un objet optionnel soit nul, soit contenant dans un de ses arguments la valeur : "timeout", "error", "abort", ou "parsererror".

Méthodes :

var jqXHR = $.get(url, [yourData], [success(dataReceived, textStatus, jqXHR)], [dataType]);

var jqXHR = $.post(url, [yourData], [success(dataReceived, textStatus, jqXHR)], [dataType]);

var jqXHR = $.getJSON(url, [yourData], [success(dataReceived, textStatus, jqXHR)]);

$.getJSON() charge des données encodées au format JSON.

Le paramètre dataReceived contiendra un objet JavaScript ou un tableau en fonction de la structure JSON reçue et de l'analyse réalisée par la méthode $.parseJSON()$.parseJSON().

Si le fichier JSON contient une erreur de syntaxe, la demande échoue généralement sans signaler aucune erreur. Pour cette raison, évitez les fichiers JSON construits à la main s'ils n'ont pas été soumis à un vérificateur JSON. Par exemple JSV (JSON Schema Validator)JSV (JSON Schema Validator).

JSON est un format d'échange de données avec des règles de syntaxe très strictes. Par exemple, toutes les chaînes représentées dans JSON, si elles sont des propriétés ou des valeurs, doivent être placées entre guillemets (doubles-quotes, exemple : "hello"). Pour plus de détails sur le format JSON, voir http://json.org/json.

var jqXHR = $.getScript(url, [success(dataReceived, textStatus)]);

Cette méthode charge un fichier JavaScript et l'exécute.

Exemple d'utilisation :

$.getJSON('dateJSON.js', function(data, textStatus, jqXHR) {
	console.log(data, textStatus, jqXHR);
 
	// succès de la transaction, on doit traiter le contenu de data
 
}).error(function(jqXHR, textStatus, errorThrown){
	console.log(jqXHR, textStatus, errorThrown);
 
	// échec de la transaction, gérer la catastrophe
 
}).complete(function(jqXHR, textStatus){
	console.log(jqXHR, textStatus);
 
	// la transaction s'est terminée par un succès ou par un échec
});

Cas particulier :

var jQueryObject = $(selector).load(url, [yourData], [complete(dataReceived, textStatus, jqXHR)]);

Cette méthode place les données chargées depuis le serveur dans l'élément du DOM correspondant au sélecteur.

$(selector).load() ne retourne pas un objet jqXHR, ce qui interdit le chaînage des fonctions de rappel.

La fonction de rappel complete est la seule qui soit disponible. Les données reçues (dataReceived) ont donc déjà été traitées.

Pour les initiés :

Les méthodes ci-dessus suffiront dans la majorité des cas. Pour des cas particuliers, les initiés utiliseront $.ajax()$.ajax et en cas de besoin, ils pourront même modifier le protocole AJAX de jQuery.

Nota Bene :

À cause des restrictions imposées par : Cross-Origin Resource SharingCross-Origin Resource Sharing, sans un serveur pour donner les réponses attendues par le navigateur on n'obtient plus que des erreurs et des avertissements.

Ainsi je n'arrive plus à travailler sur mon ordinateur avec un simple fichier JSON et une page HTML affichée dans Firefox 3.6.13 ou Chrome 9.0.597.86. Je suis obligé de sauvegarder la page web (qui ne contient pourtant que du code HTML) comme une page PHP et d'utiliser un serveur PHP (WampServer).

Seules les transactions AJAX manipulant des scripts et du JSONP ne sont pas soumises à ces restrictions.