L'objet XMLHttpRequest plus en détails : méthodes et propriétés

L'objet XMLHttpRequest est au coeur du développement Web utilisant de l'Ajax.

Il a été développé, au départ, par Microsoft, sous Internet Explorer 5, puis généralisé aux autres navigateurs : Mozilla 1.0, Konqueror/Safari, Opera, ...
Il est en cours de standardisation par le W3C depuis avril 2006.

Nous allons ici voir quelles sont les méthodes et les propriétés définies par l'objet XMLHttpRequest.

Note : pour nos exemples, nous considérerons que vous avez une variable nommée http, qui soit une instance d'objet XMLHttpRequest.

Index

• Méthodes
  • abort
  • getAllResponseHeaders
  • getResponseHeader
  • open
  • setRequestHeader
• Propriétés
  • onreadystatechange
  • readyState
  • responseText
  • responseXML
  • status
  • statusText

Méthodes

Tout d'abord, voici les méthodes permettant de manipuler une instance d'objet XHR dans le but d'effectuer un appel Ajax :

abort()

Annule la requête en cours.

getAllResponseHeaders()

Renvoi une chaîne de caractères contenant l'intégralité des en-têtes HTTP de la réponse renvoyée par le serveur suite à la requête.

Par exemple, avec le code suivant exécuté au retour de l'appel Ajax :

alert(http.getAllResponseHeaders());

On obtiendra :

getResponseHeader(nom)

Renvoi la chaîne de caractères correspondant à la valeur d'un en-tête HTTP renvoyé par le serveur.

Par exemple, avec le code suivant :

alert(http.getResponseHeader('Server'));

On obtiendra :

open

La méthode open initialise la connexion : elle définit notamment vers quelle URL la requête Ajax sera effectuée, et via quelle méthode.
open peut être utilisée de quatre manières différentes :

open(methode, url, asynchrone, utilisateur, motDePasse)

• methode : détermine si la requête sera effectuée en 'GET', 'POST' - ou l'une des autres méthodes possibles^[1].
• url : URL vers laquelle la requête sera effectuée.
• asynchrone (true par défaut) : si true, la requête sera exécutée en arrière-plan, de manière asynchrone ; si false, le navigateur sera bloqué pendant l'exécution de la requête.
• utilisateur et motDePasse (null par défaut) : Pour s'identifier avec un couple login/password.

De ces cinq paramètres, seuls les deux premiers sont obligatoires.
open peut donc aussi être appelée des trois manières qui suivent :

open(methode, url, asynchrone, utilisateur)

Pour ne pas préciser de mot de passe.

open(methode, url, asynchrone)

Pour ne préciser ni utilisateur, ni mot de passe, tout en ayant le choix entre synchrone et asynchrone.

open(methode, url)

Pour effectuer une requête asynchrone, sans précision d'utilisateur ni de mot de passe.
Cette syntaxe correspond à l'usage le plus fréquent de l'objet XHR.

send(contenu)

La méthode send lance la requête qui a été initialisée avec open.
Elle peut prendre en paramètre, lorsque l'on est en POST, une chaîne de caractères, de la forme 'param1=valeur1&param2=valeur2', regroupant les paramètres qui doivent être passés au programme appelé.

Dans le cas où la requête est envoyée en GET, contenu vaudra null : les paramètres seront transmis dans l'URL, en second paramètre de la méthode open.

setRequestHeader(nom, valeur)

setRequestHeader ajoute une l'en-tête HTTP nom à la requête Ajax, en lui assignant valeur.

Par exemple, on peut vouloir renseigner l'en-tête If-Modified-Since, pour indiquer au programme qu'il ne doit renvoyer les données que si elles ont été modifiées depuis une certaine date.

Propriétés

A présent, quelques mots sur les propriétés que fournit l'objet XMLHttpRequest :

onreadystatechange

Au cours de sa vie - et de l'exécution de la requête - l'objet XHR passe par plusieurs états ; à chaque changement d'état, un gestionnaire d'événements peut être appelé.
Pour définir ce gestionnaire d'événements, il faut renseigner la propriété @@onreadystatechange.

Par exemple :

function monGestionnaire()
{
    // ...
}

http.onreadystatechange = monGestionnaire;

Ou alors :

http.onreadystatechange = (
        function ()
        {
            // ...
        }
    );

readyState

A chaque changement d'état de l'objet XHR, le gestionnaire d'événements défini ci-dessus sera appelé.
Pour savoir en quel état se trouve l'objet XHR, notamment au sein de la méthode définie comme gestionnaire d'événements, il faut utiliser la propriété readyState.

Voici les valeurs, numériques, qu'elle peut prendre (les libellés correspondant uniquement à la signification usuelle de chaque code de statut) :

• 0 : Uninitialized : Valeur initiale, lorsque l'objet n'a pas été initialisé. Entre sa création, et l'appel de la méthode open, donc.
• 1 : Open : Une fois que l'objet a été initialisé via la méthode open, mais que la requête n'a pas encore été déclenchée par la méthode send.
• 2 : Sent : Une fois la requête envoyée par la méthode send.
• 3 : Receiving : Avant la réception du corps de la réponse. Les en-têtes HTTP de la réponse ont déjà été reçus, eux, par contre.
• 4 : Loaded : Quand la réponse a été entièrement reçue : l'appel Ajax est terminé ; il est possible d'utiliser son résultat.

responseText

Lorsque la requête Ajax est terminée - readyState vaut 4 - la propriété responseText de l'objet XHR contient le corps de la réponse, sous forme d'une chaîne de caractères.

Par exemple, si le programme appelé par l'appel Ajax est le suivant :

<?php
    echo '<strong>Hello</strong> World !';
?>

Alors,

alert(http.responseText);

Affichera "<strong>Hello</strong> World !" - sans que les éventuelles balises ne soient interprétées d'une quelconque manière.
Bien entendu, si vous utilisez cette réponse pour renseigner le contenu d'un élément de votre document, comme ceci :

document.getElementById('monElement').innerHTML = http.responseText;

Alors les balises HTML de présentation (Pas celles de script)^[2] seront interprétées.
Par exemple, si votre programme est le suivant :

<?php
    echo '<strong>Hello</strong> World !<script type="text/javascript">alert(\'glop\');</script>';
?>

Alors, vous obtiendrez l'affichage de "Hello World !" dans l'élément monElement ; mais "glop" ne sera pas affiché.

responseXML

L'attribut responseXML, quand à lui, correspond à la réponse sous forme d'un document DOM XML, qui peut être manipulé par les méthodes DOM W3C.

Par exemple, si notre programme côté serveur génère des données XML, de cette manière :

<?php
    header('Content-Type: text/xml; charset: UTF-8');
    echo '<?xml version="1.0" encoding="UTF-8" ?>';
?>
<root>
    <personne>
        <nom>Lerdorf</nom>
        <prenom>Rasmus</prenom>
    </personne>
    <personne>
        <nom>Gutmans</nom>
        <prenom>Andi</prenom>
    </personne>
    <personne>
        <nom>Suraski</nom>
        <prenom>Zeev</prenom>
    </personne>
</root>

Nous pourrons les lire en Javascript, par exemple en vue d'affichage^[3] :

var xml = http.responseXML;

var str = '';
for (i=0 ; i<xml.getElementsByTagName('personne').length ; i++)
{
    var personne = xml.getElementsByTagName('personne')[i];
    var nom = personne.getElementsByTagName('nom')[0].firstChild.nodeValue.toUpperCase();
    var prenom = personne.getElementsByTagName('prenom')[0].firstChild.nodeValue
    str += prenom + ' ' + nom + '<br />';
}

document.getElementById('resultat').innerHTML = str;

Ce qui nous donnera la sortie suivante :

Rasmus LERDORF
Andi GUTMANS
Zeev SURASKI

status

Une fois la requête terminée, la propriété status de l'objet XMLHttpRequest permet d'obtenir le code de statut HTTP de la requête.

Par exemple :

• 404 pour une page non trouvée
• 200 Pour une requête réussie
• ...

La liste des codes statut HTTP est disponible en ligne.

statusText

Le texte correspondant au code statut HTTP.

Par exemple :

• "Not Found" pour une page non trouvée (status = 404)
• "OK" en cas de succès (status = 200)
• "Forbidden" pour un accès refusé (status = 403)
• ...

Pour terminer, je ne peux que vous conseiller de jeter un coup d'oeil sur la page du Working Draft du W3C concernant l'objet XMLHttpRequest, qui vous apportera sans aucun doute quelques informations supplémentaires utiles.
Prêtez tout particulièrement attention aux notions : "must", "should", "may", ... qui ont chacune leur signification.

Mises à jour

• MAJ le samedi 27 janvier 2007 : Ajout de l'index