Comment dois-je formuler une requête AJAX ?

Index

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.

Les méthodes $.get(), $.post(), $.getJSON(), $.getScript() et $(selector).load() exécutent la majorité des transactions AJAX dont vous aurez besoin. Toutes les 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 du serveur vers laquelle la demande est envoyée.
yourData
Un objet au format JSON 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() : encode tous les éléments d'un formulaire, ayant un attribut name, sous forme d'un tableau de paires "key/value" ;
  • $( selector ).serialize() : encode tous les éléments d'un formulaire, ayant un attribut name, comme une chaîne de caractères ;
  • $.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 ] );

var jqXHR = $.post( url, [ yourData ] );

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

var jqXHR = $.getScript( url );

$( selector ).load( url, [ yourData ], [ function( dataReceived, textStatus, jqXHR ){ ... } ] );

Exploitation de l'objet différé jqXHR

/*
 * Succès de la transaction, on doit traiter 
 * le contenu de data.
 */
jqXHR.done( function( data, textStatus, jqXHR ){
    /*
     * Debug, console, touche F12
     */
    console.log( data, textStatus, jqXHR );
    
    // votre code en cas de succès
});

/*
 * Échec de la transaction, on doit gérer 
 * la catastrophe.
 */
jqXHR.fail( function( jqXHR, textStatus, errorThrown ){
    /* 
     * Debug, console, touche F12
     */
    console.log( jqXHR, textStatus, errorThrown );
    
    // votre code en cas d'échec
});

/*
 * La transaction AJAX est terminée (succès 
 *  ou échec).
 * 
 * Usage optionel, si vous devez faire "le ménage"
 * après la transaction AJAX, c'est ici !
 */
jqXHR.always( function( jqXHR, textStatus ){
    /*
     * La transaction AJAX est terminée (succès 
     *  ou échec).
     * 
     * Debug, console, touche F12
     */
    console.log( jqXHR, textStatus );
    
    // votre code pour faire "le ménage".
});

En raison de restrictions de sécurité imposées par Cross-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.

Exemple : transaction JSON et JSONP

Code client en JSON : var jqXHR = $.getJSON( url, [ yourData ] );

Code client en JSONP : var jqXHR = $.getJSON( url + "?callback=?", [ yourData ] );

Code serveur : le même code PHP, traite la demande de JSON ou de JSONP.

Pour des besoins particuliers

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

Tests unitaires avec QUnit.