Suite à la demande d'un visiteur du site, je vais vous expliquer tout au long de ce tutoriel comment fonctionne la fonction jQuery.ajax() du framework jQuery et comment vous en servir.

Nous commencerons par l'aspect théorique à la base d'AJAX, à savoir, l'objet Javascript XMLHttpRequest. Si la théorie ne vous intéresse pas et que vous souhaitez passer tout de suite à la pratique, aucun problème, vous pouvez passer ce chapitre, je ne vous en voudrais pas, promis.

Definition

AJAX signifie Asynchronous Javascript And XML (Javascript et XML Asynchrone). Je ne serais pas contre le fait de remplacer XML par JSON qui est de plus en plus utilisé. On en reparlera plus loin.

Javascript et XML, okay, je vois, mais asynchrone, c'est quoi ça ? Pour faire simple, lorsque vous accédez à une page d'un site web, vous ne pouvez rien faire tant que le site web (le serveur) ne vous a pas envoyé la page, vous devez attendre. On dit alors que le requête est synchrone. A l'opposé, avec AJAX, vous pouvez faire des requêtes au serveur et continuer à faire ce que vous souhaitez sur la page sans attendre la réponse du serveur. La requête est alors asynchrone.

XMLHttpRequest

XMLHttpRequest est un object Javascript implémenté dans tous les navigateurs actuels (je considère que votre navigateur est à jour, vous n'êtes pas des noobs quand même). C'est cet objet qui nous permet de faire des requêtes asynchrones. Vous pouvez l'utiliser tel quel dans votre code Javascript mais il y a un peu de configuration à faire à chaque fois et à la longue, c'est penible. Qui plus est, des gens bien plus compétents que nous en Javascript se sont donnés la peine d'intégrer cet objet à jQuery via la fonction jQuery.ajax(). Il nous sera bien plus simple d'utiliser cette fonction plutôt que de configurer l'objet XMLHttpRequest à chaque fois.

La théorie est maintenant terminée, passons à la pratique.

La fonction jQuery.ajax requière plusieurs paramètres (dans un objet JSON) pour fonctionner. On l'appelle de la façon suivante :

$(document).ready(function() {

  jQuery.ajax({
    // Mes paramètres ici
  });

});

J'ai ici encapsulé la fonction dans $(document).ready(function () {...}); pour vous rappeler qu'il est nécessaire de faire cela pour que jQuery fonctionne correctement. Je l'omettrai dans la suite de ce tutoriel.

Commençons par les paramètres essentiels, sans qui la fonction n'aurait aucun sens, à savoir :

• Le type de requête (GET, POST, PUT, DELETE)
• L'URL vers laquelle on va envoyer la requête
• Les données que l'on souhaite envoyer
• Que faire en cas de succès de la requête (HTTP 2xx)
• Que faire en cas d'erreur de la requête (HTTP 4xx ou 5xx)

Comme je l'ai dis plus haut, nous devons passer ces paramètres dans un objet JSON. Si vous ne savez pas comment on décrit un object JSON en Javascript, rien de plus simple, c'est un système de clé - valeur que vous devez mettre entre accolades comme ceci :

{
  cle1: "valeur 1",
  cle2: 127,
  cle3: false
  cle4: function() {
    alert('Hello World!');
  }
}

Nous pouvons maintenant passer à nos paramètres. De ceux que j'ai cité plus haut, le type de requête est par défaut à GET. Si c'est ce type de requête que vous souhaitez effectuer, vous n'avez donc pas besoin de le préciser.

jQuery.ajax({
  type: 'GET', // Le type de ma requete
  url: 'http://www.monsite.com/serveur.php', // L'url vers laquelle la requete sera envoyee
  data: {
    username: 'OyoKooN', // Les donnees que l'on souhaite envoyer au serveur au format JSON
    age: 19,
    admin: true
  }, 
  success: function(data, textStatus, jqXHR) {
    // La reponse du serveur est contenu dans data
    // On peut faire ce qu'on veut avec ici
  },
  error: function(jqXHR, textStatus, errorThrown) {
    // Une erreur s'est produite lors de la requete
  }
});

Comme vous pouvez le voir, j'envoi des données au serveur à l'aide du paramètre data. Ce paramètre est optionnel, si vous n'avez rien à envoyer au serveur, vous pouvez omettre ce paramètre. Comme ici, nous utilisons le type GET pour faire la requête, les paramètres de data seront passé dans l'url. Ainsi, la requête fera appel à la page http://www.monsite.com/serveur.php?username=OyoKooN&age=19&admin=true. Si nous avions envoyé une requête de type POST, les paramètres auraient été envoyé dans l'en-tête HTTP et non pas dans l'URL.

Si ça vous intéresse de voir ce qu'il se passe lorsque vous faites une requête AJAX ou même pour debugger votre code, téléchargez le plugin Firebug pour Firefox et ouvrez l'onglet Console. Vous pourrez voir toutes les requêtes comme sur l'image ci-dessous.

Nous passons ensuite au paramètre success qui prend la forme d'une fonction anonyme. Le seul argument de cette fonction qui nous intéresse est data. A l'intérieur de la fonction anonyme, la variable data contient la réponse du serveur. Admettons que le serveur se content de l'instruction PHP suivante :

<?php
echo "Hello World!";
?>

La variable data contiendra alors Hello World!.

Enfin, le paramètre error prend lui aussi la forme d'une fonction anonyme de 3 arguments dont on se fiche royalement, ils ne sont généralement pas d'un grand secours pour nous aider à comprendre où ça coince, mieux vaut utiliser Firebug.

Ces paramètres sont ceux que vous utiliserez le plus souvent. Sachez qu'il y en a d'autres que vous pouvez retrouvez dans la documentation de jQuery (voir lien en conclusion).

Si vous utilisez intensément la fonction jQuery.ajax() dans vos fichiers Javascript, vous pouvez appeler la fonction jQuery.ajaxSetup au début de vos fichiers et lui passer tous les paramètres récurrents dans votre application. Ils deviendront paramètres par défaut de toutes les futures requêtes AJAX.

Je vais maintenant vous donner le code de l'exemple que vous pourrez retrouver en démonstration. Côté serveur, nous avons un fichier PHP nommé register_username.php et contenant le code suivant.

<?php
session_start();

if (isset($_POST['username'])) {
  $_SESSION['username'] = $_POST['username'];
}
?>

C'est tout con mais ça suffit à vous montrer ce que je veux. Maintenant, sur notre page HTML, nous avons un formulaire contenant un champ pour le nom d'utilisateur et un bouton pour envoyer les données. Le formulaire contient une instruction PHP qui affichera votre nom d'utilisateur si celui-ci est enregistré en session. La première fois que vous allez sur la page, vous ne devez rien voir normalement.

<fieldset>
  <legend>Entrez vos informations</legend>
  <div id="classic-use-response">
    <? if (isset($_SESSION['username'])) : ?>
      <p style="color:orange;"><strong>Le nom d'utilisateur enregistré en session est <i><?= $_SESSION['username']; ?></i>.</strong></p>
    <? endif; ?>
  </div>

  <div>
    <label for="username">Nom d'utilisateur : </label>
    <p class="input">
      <input type="text" id="username" placeholder="Votre nom d'utilisateur" />
    </p>
    <button id="classic-use-button">Envoyer les données</button>
  </div>
</fieldset>

Il est normalement de bon ton de mettre une balise <form> et un bouton <input type="submit" /> afin que les visiteurs n'ayant pas activé Javascript puisse quand même utiliser le formulaire.

A présent, nous pouvons nous consacrer sur la partie intéressante à savoir le code Javascript.

var loader = "assets/images/loader.gif";

$('#classic-use-button').click(function() {

  // Recuperation du nom d'utilisateur
  var username = $('#username').val();

  // Si le nom d'utilisateur est vide on signale l'erreur
  if (username.length < 1) {
    $('#classic-use-response').html('').html('<div class="error">Le nom d\'utilisateur ne doit pas être vide.</div>');
    // Sortie de la fonction, on ne va pas plus loin
    return false;
  }

  // Si on arrive ici c'est que le nom d'utilisateur est fourni
  // On va donc signaler que nous sommes en train de faire quelque chose à l'aide d'une petite image
  $('#classic-use-response').html('').html('<img src="' + loader + '" alt="#" />&nbsp;Chargement...');

  // Maintenant nous pouvons commencer l'envoi des donnees
  $.ajax({
    url: 'register_username.php',
    type: 'POST',
    data: {
      username: username
    },
    error: function(jqXHR, textStatus, errorThrown) {
      // En cas d'erreur, on le signale
      $('#classic-use-response').html('').html('<div class="error">Une erreur est survenue lors de la requête.</div>');
    },
    success: function(data, textStatus, jqXHR) {
      // Succes. On affiche un message de confirmation
      $('#classic-use-response').html('').html('<div class="success">Nom d\'utilisateur enregistré en session. Vous pouvez <a href="' + window.location + '">rechargez la page</a> pour le voir.</div>');
    }
  });

});

Le code ci-dessus utilise les paramètres que nous avons vu tout à l'heure. Vous devriez donc pouvoir le comprendre par vous même.

Ma fonction ajax est liée à un évènement, le click sur le bouton ayant l'id #classic-use-button. Lorsque l'utilisateur appuie sur ce bouton, le code récupère le nom d'utilisateur entré dans le champ du formulaire et verifie que ce n'est pas une chaine vide.

Nous insérons ensuite dans la page web une image ainsi qu'un petit mot indiquant que la requête est en cours de traitement. Nous envoyons ensuite les données vers le fichier PHP à l'aide d'une requête de type POST.

Enfin, lors de la réponse du serveur, que ce soit un echec ou un succès, nous remplaçons l'image de chargement par un message.

N'hesitez pas à vous rendre sur la page de démonstration si vous avez des doutes sur le fonctionnement du code.

La fonction jQuery.ajax() peut prendre un paramètre dont je n'ai pas parlé tout à l'heure, dataType. Ce paramètre sert à préciser le type de réponse que vous attendez du serveur. Par exemple html, json ou xml. Quand vous ne précisez pas ce paramètre, jQuery devine à quel type de réponse il doit se préparer grâce aux en-têtes HTTP.

Tout ça pour dire que pour certains cas, la fonction jQuery.ajax() a des alias avec des paramètres prédefinis. Pour récupérer du contenu JSON, il est plus judicieux d'utiliser la fonction jQuery.getJSON car celle ci parsera automatiquement la réponse du serveur afin que vous puissiez utiliser directement le code JSON ainsi récupéré.

Son fonctionnement est un plus simple que la fonction précédente car elle ne prend en paramètres que l'URL où récupérer le JSON et une fonction anonyme permettant de manipuler la réponse du serveur.

La voici telle qu'elle est sur la page de démonstration.

$.getJSON('get_json.php', function(data) {

  // Construction d'une liste contenant les donnees JSON
  var output = "<ul>";

  // On passe en revue les cles et valeurs une a une
  $.each(data, function(key, value) {
    output += '<li><strong>' + key + ' : </strong>' + value + '</li>';
  }); 

  output += "</ul>"

  // Enfin on insere la liste dans la page
  $('#json-use-response').html('').html(output);

});

Le fichier PHP répondant à la requête est le suivant :

<?php
$json = array(
  "username" => "OyoKooN",
  "age"      => 19
);
echo json_encode($json);
?>

Vraiment simple n'est-ce pas ? Ici, la seule petite difficulté réside dans l'utilisation de la fonction jQuery.each() qui permet de boucler sur une collection ou un objet.

De la même manière que la fonction précédente, jQuery.get va aller chercher un contenu sur le serveur mais n'importe quel type de contenu cette fois. Ce sera donc à vous de traiter les données que vous recevrez et de les parser si nécessaire.

$.get('get_comic.php', function(data) {

  // On recupere du HTML donc on l'insere "as-is" dans la page
  $('#get-use-response').html('').html(data);

});

Le fichier PHP répondant à la requête :

<?php
echo '<div><img src="internet-cat" alt="Internet Cat" /><p>The Oatmeal</p></div>';
?>

Ici, je me contente d'insérer le résultat dans la page car je sais que le serveur va me renvoyer du code HTML.

Sachez que l'équivalent pour POST existe : jQuery.post().

Ce tutoriel est maintenant terminé, j'espère que les notions que nous avons abordé ensemble vous servirons par la suite dans vos projets web. Il existe tout un tas d'options que vous pouvez passer à la fonction jQuery.ajax() dont je n'ai pas parlé ici. Libre à vous d'aller les consuler sur la documentation officielle.

N'hésitez pas à laisser un commentaire sur le tutoriel, ou à le partager sur les réseaux sociaux, ça me fait toujours plaisir et m'encourage à continuer mon oeuvre pour un monde meilleur.

Si le tutoriel contient un point que vous ne comprenez pas, sur lequel vous aimeriez avoir des explications, n'hésitez pas à poser votre question sur le Google Group de Syrinxoon Tuts, je viendrai rapidement répondre à votre question.

Enfin, signe ultime de remerciement, vous pouvez me faire un don pour m'aider à payer les frais du serveur en cliquant sur le bouton Donate ci-dessous ⇓