Fonctionnement de jQuery.ajax()

Grâce à AJAX, il est possible d'exécuter du code serveur (ex : PHP ou C#) à partir d'un appel JavaScript. Ce code peut effectuer n'importe quelle tâche côté serveur pour répondre à nos besoins : valider des informations, effectuer une lecture dans la base de données, ajouter un enregistrement dans une table, manipuler des variables de session, etc.

▼Publicité

Un appel AJAX à l'aide de jQuery prendra la forme suivante :

JavaScript 

var jqxhr = $.ajax({

    type: "POST",

    url: "NomPageWeb",

    dataType: "json",

    contentType: "application/json; charset=UTF-8",  // ou, pour un POST en PHP, contentType: "application/x-www-form-urlencoded; charset=UTF-8"  

    data: "{cle:'" + valeur + "'}"

})

.done(function (response, textStatus, jqXHR) {

    // Appel réussi : on réagit à la valeur de retour du code serveur

    // contenue dans le paramètre response (ou response.d avec ASP.NET)

    ...

})

.fail(function (jqXHR, textStatus, errorThrown) {

    // Réagit si le code serveur n'a pas pu être appelé par AJAX ou s'il a planté

    ...

})

.always(function (jqXHR, textStatus, errorThrown) {

    // Réagit dans tous les cas

    ...

});

Remarquez la syntaxe pour envoyer les données au format JSON. Les apostrophes, qui pourraient être remplacées par des guillemets, sont optionnelles alentour de la clé. Pour la valeur, tout dépend de son type. Les apostrophes sont obligatoires alentour des valeurs de type chaîne. Elles sont optionnelles lorsqu'il s'agit d'un nombre. Dans tous les cas, lorsqu'elles sont utilisées, il faut s'assurer que pour chaque apostrophe de début, il y ait également une apostrophe de fin.

Attention : si vous effectuez l'appel AJAX dans un programme ASP.NET, la valeur de retour du code serveur sera disponible dans response.d et non dans response. De plus, le code serveur sera contenu dans une fonction statique alors on précisera l'URL sous la forme NomPageWeb/NomFonctionServeur.

Éléments de configuration

Pour que l'appel AJAX soit correctement effectué, il faut bien comprendre le fonctionnement de chacun des éléments de configuration de jQuery.ajax().

type:

Lors d'une requête AJAX, les données échangées entre le client et le serveur peuvent être de type GET (données encodées directement dans l'URL) ou de type POST (données envoyées au serveur à l'aide d'un mécanisme invisible pour l'usager).

Les requêtes GET sont plus rapides. Mais pour des raisons de sécurité, on réservera leur utilisation pour les appels qui n'ont pas besoin de paramètres.

Dans tous les autres cas, on préférera l'utilisation de POST.

url:

Cet élément de configuration permet de préciser le nom de la page Web dans laquelle se trouve le code serveur à exécuter (ex : traitement.php). 

Dans le cas d'un programme ASP.NET, l'URL sera composé du nom de la fonction statique à exécuter, précédé nom de la page Web dans laquelle la fonction statique est définie. Le tout sera sous le format NomPageWeb/NomFonctionServeur (ex : Produits.aspx/EnregistrerProduit).

dataType:

Cet élément de configuration indique le type de données retourné par le code serveur. Attention : c'est ce que jQuery.ajax() recevra du code serveur et non ce que jQuery.ajax() lui enverra.

On retrouvera généralement un des types suivants : json, xml, html, jsonp, text ou script. 

Afin de vous assurer d'attendre le bon type, il faut vérifier la valeur de retour du code serveur.

Si vous ne spécifiez pas le type attendu, jQuery tentera de deviner le type en lisant le type MIME des données reçues. 

Par contre, si vous spécifiez un type attendu qui ne correspond pas à ce que le code serveur retourne, la valeur retournée sera mal encodée. 

contentType:

À l'inverse, on spécifie le format des données envoyées par jQuery.ajax() au code serveur à l'aide de l'élément contentType: (ex : contentType: "application/json; charset=UTF-8" : ceci indique que le code serveur recevra des données JSON encodées en UTF-8). Ces données sont transférées au code serveur à l'aide de l'élément data:.

Il existe de nombreux encodages disponibles. En voici quelques exemples :

  • application/x-www-form-urlencoded (valeur par défaut). C'est cette valeur que vous devez utiliser pour effectuer un appel AJAX de type POST en PHP et ce, même si les données envoyées au serveur sont au format JSON.
  • application/json. C'est cette valeur que vous devez utiliser avec ASP.NET lorsque vos données sont au format JSON.
  • application/atom+xml
  • text/css
  • text/javascript
  • image/jpeg
  • application/pdf
  • application/rss+xml; charset=ISO-8859-1
  • text/plain
  • text/xml

data:

Il s'agit des données que jQuery.ajax() envoie au code serveur. Le format doit respecter ce qui est attendu par le code serveur.

Notez que dans le cas d'une requête GET, jQuery se chargera d'encoder les données dans l'URL.

Chaîne au format JSON

Dans le format JSON, on retrouve une série de paires clé:valeur, le tout placé entre accolades. Si plus d'une paire est nécessaire, on séparera chaque paire par une virgule.

Les apostrophes, qui pourraient être remplacées par des guillemets, sont optionnelles alentour de la clé. 

Pour la valeur, tout dépend de son type. Les apostrophes sont obligatoires alentour des valeurs de type chaîne. Elles sont optionnelles lorsqu'il s'agit d'un nombre.

Dans tous les cas, lorsqu'elles sont utilisées, il faut s'assurer que pour chaque apostrophe de début, il y ait également une apostrophe de fin.

Les notations suivantes sont donc toutes valides :

data: "{cat_id:" + cat_id + "}"

data: "{cat_id:'" + cat_id + "'}"

data: "{'cat_id':'" + cat_id + "'}"

PlainObject

En JavaScript, le type PlainObject est lui aussi composé d'une série de paires clé:valeur, le tout entouré d'accolades. Cependant, il n'y aura pas de guillemets pour entourer le tout, comme c'était le cas avec les chaînes JSON. On obtient donc un objet JavaScript et non une chaîne.

Ex : data: {cat_id:1}

Appels AJAX ne nécessitant l'envoi d'aucune donnée

Dans le cas où le code serveur n'attend aucun paramètre, il faut tout de même préciser un élément data: avec des accolades vides.

Ex : data: "{ }"

Fonction jqXHR.done()

La fonction jqXHR.done() reçoit en paramètre une fonction de rappel qui permet de préciser le comportement du programme lorsque l'appel AJAX est réussi. Il s'agira souvent d'une fonction anonyme.

C'est dans cette fonction de rappel qu'on pourra utiliser les données retournées par le code serveur.

Cette fonction reçoit en paramètre :

  • response : un objet représentant les données retournées par le code serveur
  • textStatus : une chaîne indiquant l'état de l'opération (valeur : success)
  • l'objet jqXHR : un objet contenant des informations sur l'appel AJAX.

C'est généralement le premier paramètre (response) qui nous intéresse. 

Prenez note qu'afin de protéger le code contre certaines attaques XSS, ASP.NET a encapsulé la réponse du serveur dans un objet. Les données effectivement retournées sont disponibles dans la propriété d de cet objet. C'est pourquoi on travaillera avec response.d sous ASP.NET alors qu'en PHP, on travaillera directement avec response.

Fonction jqXHR.fail()

La fonction jqXHR.fail() reçoit en paramètre une fonction de rappel qui permet de préciser le comportement du programme lorsque l'appel AJAX n'est pas réussi. 

Un appel AJAX ne sera pas réussi si les éléments de configuration de jQuery.ajax() ne sont pas corrects ou encore si le code serveur plante.

La fonction de rappel reçoit trois paramètres :

  • l'objet jqXHR : un objet contenant des informations sur l'appel AJAX. La propriété jqXHR.responseText contient le code HTML donnant de l'information complète sur l'erreur. Faites bien attention de ne jamais afficher ce texte à l'écran. Le débogueur JavaScript sera votre meilleur outil pour vérifier le contenu de cette propriété.
  • textStatus : une chaîne indiquant l'état de l'erreur. Les valeurs possibles sont null, « timeout », « error », « abort » et« parsererror ».
  • errorThrown : texte donnant de l'information sur l'erreur. Ex : « Not Found », « Internal Server Error ».

Fonction jqXHR.always()

La fonction jqXHR.always() reçoit en paramètre une fonction de rappel qui permet de préciser le comportement du programme après l'appel AJAX, que l'appel ait été réussi ou non. 

Succès et erreur : utilisation de fonctions vs éléments de configuration

On retrouve souvent les appels à la fonction jQuery.ajax() dans lesquels le traitement en cas de succès ou d'erreur est précisé à l'aide d'éléments de configuration success:, error: et complete:, comme illustré plus bas. Bien que ceci fonctionne parfaitement, cette technique est désormais moins utilisée puisque depuis jQuery 1.5, les fonctions .done(), .fail() et .always() offrent une syntaxe améliorée. 

C'est pourquoi on préférera l'utilisation des fonctions .done() et .fail(), comme illustré plus haut.

JavaScript 

$.ajax({

    type: "POST",

    url: "NomPageWeb",

    dataType: "json",

    contentType: "application/json; charset=utf-8",

    data: "{cle:'" + valeur + "'}",

    success: function (response, textStatus, jqXHR) {

        ...

    },

    error: function (jqXHR, textStatus, errorThrown) {

        ...

    },

    complete: function (jqXHR, textStatus) {

        ...

    }

});

Pour plus d'information

« jQuery.ajax() ». jQuery. http://api.jquery.com/jquery.ajax/

Merci de partager ! Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInPin on PinterestShare on StumbleUponEmail this to someone
Catégories