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.
Les appels AJAX utilisent la technologie XMLHttpRequest (dont l'abbréviation est XHR).
L'utilisation directe de XHR est plutôt complexe. Mais avec jQuery, les appels AJAX sont de beaucoup simplifiés.
Je vous présente ici la méthode la plus versatile : jQuery.ajax(). jQuery nous offre également des méthodes plus simples à utiliser, par exemple jQuery.get() ou jQuery.post(). Ces méthodes donnent des valeurs par défaut à plusieurs des configurations de jQuery.ajax().
Un appel AJAX à l'aide de jQuery prendra la forme suivante :
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
...
})
.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.
L'appel AJAX retourne une référence à l'objet jQuery qui a été créé pour communiquer avec le serveur. Il s'agit d'un objet de type XMLHttpRequest, que l'on nomme généralement jqXHR.
Puisque l'appel jQuery.ajax() prévoit directement le code à exécuter lorsque l'appel est terminé avec succès (.done()), avec erreur (.fail()) ou dans tous les cas (.always()), et que ces méthodes reçoivent elles-mêmes en paramètre une référence à l'objet jqXHR, cette valeur de retour est rarement utilisée.
Il est donc possible de faire l'appel AJAX sans tenir compte de la valeur de retour.
Ex :
$.ajax({
type: ...,
url: ...,
dataType: ...,
contentType: ...,
data: ...
})
.done(function (response, textStatus, jqXHR) {
// Appel réussi : on réagit à la valeur de retour du code serveur
// contenue dans le paramètre response
...
})
.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
...
});
Pour que l'appel AJAX soit correctement effectué, il faut bien comprendre le fonctionnement de chacun des éléments de configuration, aussi appelés options, de jQuery.ajax().
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.
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).
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. Dans la cas où la fonction serveur retourne autre chose comme un booléen, par exemple, il est préférable de modifier la fonction serveur pour qu'elle convertisse sa valeur de retour au format JSON.
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.
À 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 :
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.
En JavaScript, le type PlainObject est très utile pour passer les valeurs à la configuration data.
Il est composé d'une série de paires clé:valeur, le tout entouré d'accolades.
Si plus d'une paire est nécessaire, on séparera chaque paire par une virgule.
Exemples avec des variables :
data: {produit_id : produit_id}
data: {produit_id : produit_id, description : description}
Exemple avec des valeurs codées en dur :
data: {produit_id : 3}
data: {produit_id : 3, description : 'lorem ipsum'}
Dans le cas où le code serveur n'attend aucun paramètre, il peut arriver qu'on ait tout de même besoin de préciser un élément data: avec des accolades vides.
Ex : data: "{ }"
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 :
C'est généralement le premier paramètre (response) qui nous intéresse.
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 :
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.
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.
Les éléments de configuration success:, error: et complete: peuvent encore être utiles, notamment si on utilise la configuration async: false puisque ceci ne permet plus d'utiliser les fonctions .done(), .fail() et .always().
As of jQuery 1.8, the use of async: false with jqXHR ($.Deferred) is deprecated; you must use the success/error/complete callback options instead of the corresponding methods of the jqXHR object such as jqXHR.done(). 1
En résumé, on préférera l'utilisation des fonctions .done() et .fail(), comme illustré plus haut, sauf dans le cas où on utilise la configuration async: false.
$.ajax({
type: "POST",
url: "NomPageWeb",
dataType: "json",
contentType: "application/json; charset=utf-8",
data: "{cle:'" + valeur + "'}",
});
Note : avant jQuery 3.0, il y avait des fonctions jqXHR.success(), jqXHR.error() et jqXHR.complete(). Il ne faut pas les confondre avec les éléments de configuration success:, error: et complete:. Les premières (sous forme de fonction) sont obsolètes mais les éléments de configuration peuvent encore être utilisés.
Deprecation Notice: The jqXHR.success(), jqXHR.error(), and jqXHR.complete() callbacks are removed as of jQuery 3.0. You can use jqXHR.done(), jqXHR.fail(), and jqXHR.always() instead. 1
« jQuery.ajax() ». jQuery. http://api.jquery.com/jquery.ajax/
« jQuery.ajax handling continue responses: “success:” vs “.done”? ». Stack Overflow. https://stackoverflow.com/questions/8840257/jquery-ajax-handling-continue-responses-success-vs-done
« Deprecation of success Parameter in jQuery.ajax? ». Stack Overflow. https://stackoverflow.com/questions/15821141/deprecation-of-success-parameter-in-jquery-ajax
▼Publicité
