Évènements online et offline

Aperçu

Afin de construire une bonne application Web capable de fonctionner hors ligne, il est nécessaire de savoir quand votre application est hors ligne. De même, vous devrez également savoir quand votre application est de nouveau en ligne. Concrètement, ce qui est nécessaire se résume à :

  1. Savoir quand l'utilisateur est de nouveau en ligne, afin de se resynchroniser avec le serveur.
  2. Savoir quand l'utilisateur est hors ligne, afin de s'assurer que les requêtes à faire vers le serveur soient bien enregistrées localement.

C'est ce processus que les évènements online et offline rendent presque trivial.

Votre application web peut également vouloir indiquer que certains documents doivent être maintenus dans le cache des ressources hors ligne. Pour en savoir plus sur la manière de préciser cette indication, consultez l'article Ressources hors ligne dans Firefox.

API

navigator.onLine est une propriété qui maintient une valeur true/false (true pour online, false pour offline). Cette propriété est mise à jour chaque fois que l'utilisateur passe en mode « Hors ligne » en sélectionnant l'entrée de menu correspondante (Fichier → Travailler hors connexion dans Firefox).

De plus, cette propriété doit être mise à jour dès que le navigateur n'arrive plus à se connecter au réseau. D'après la spécification :

L'attribut navigator.onLine doit renvoyer false si l'agent utilisateur ne va pas contacter le réseau lorsque l'utilisateur suit un lien ou lorsqu'un script demande une page distante (ou sait qu'une telle tentative échouerait)…

Firefox 2 met à jour cette propriété lors du passage en mode hors connexion du navigateur, et lors de la perte ou de la récupération de la connectivité réseau sous Windows et Linux.

Cette propriété existait dans de versions plus anciennes de Firefox et Internet Explorer (la spécification se base sur ces implémentations précédentes), vous pouvez donc immédiatement commencer à l'utiliser. La détection de l'état du réseau a été ajoutée dans Firefox 2.

Les évènements « online » et « offline »

Firefox 3 introduit deux nouveaux évènements : « online » et « offline ». Ces deux évènements sont déclenchés sur l'élément <body> de chaque page lorsque le navigateur passe d'un mode à l'autre. De plus, les évènements se propagent depuis document.body, vers document, puis vers window. Aucun de ces deux évènements n'est annulable (il n'est pas possible d'empêcher l'utilisateur de passer en ligne ou hors ligne).

Vous pouvez ajouter des gestionnaires pour ces évènements selon les manières habituelles :

  • en utilisant addEventListener sur window, document ou document.body
  • en définissant les propriétés .ononline ou .onoffline sur document ou document.body vers un objet JavaScript Function. (Note : l'utilisation de window.ononline ou window.onoffline ne fonctionnera pas, pour des raisons de compatibilité.)
  • en spécifiant les attributs ononline="…" ou onoffline="…" à la balise <body> dans le balisage HTML.

Exemple

Un cas de test simple peut être exécuté pour vérifier que les évènements fonctionnent. XXX When mochitests for this are created, point to those instead and update this example -nickolay

 <!doctype html>
 <html>
 <head>
   <script>
     function updateOnlineStatus(msg) {
       var status = document.getElementById("status");
       var condition = navigator.onLine ? "ONLINE" : "OFFLINE";
       status.setAttribute("class", condition);
       var state = document.getElementById("state");
       state.innerHTML = condition;
       var log = document.getElementById("log");
       log.appendChild(document.createTextNode("Évènement : " + msg + " ; état=" + condition + "\n"));
     }
     function loaded() {
       updateOnlineStatus("load");
       document.body.addEventListener("offline", function () {
         updateOnlineStatus("offline")
       }, false);
       document.body.addEventListener("online", function () {
         updateOnlineStatus("online")
       }, false);
     }
   </script>
   <style>...</style>
 </head>
 <body onload="loaded()">
   <div id="status"><p id="state"></p></div>
   <div id="log"></div>
 </body>
 </html>

Références