Online and offline events

  • Revision slug: Online_and_offline_events
  • Revision title: Online and offline events
  • Revision id: 79903
  • Created:
  • Creator: Mgjbot
  • Is current revision? No
  • Comment robot Adding: [[pl:Zdarzenia online i offline]] <<langbot>>

Revision Content

{{template.Fx_minversion_header(3)}} Firefox 3 implements Online/Offline events from the WHATWG Web Applications 1.0 specification.

Overview

In order to build a good offline-capable web application, you need to know when your application is actually offline. Incidentally, you also need to know when your application has returned to an 'online' status again. Effectively, the requirements break down as such:

  1. You need to know when the user comes back online, so that you can re-synchronize with the server.
  2. You need to know when the user is offline, so that you can be sure to queue your server requests for a later time.

It is this process that online/offline events help to trivialize.

Your web application may also need to establish that certain documents be maintained in the offline resources cache. To do so, include LINK elements in your HEAD section like this:

<link rel="offline-resource" href="myresource">

When Firefox 3 or later processes the HTML, this will cause the resource referenced to be cached for offline use in a special offline resource cache.

API

navigator.onLine

navigator.onLine is a property that maintains a true/false value (true for online, false for offline). This property is updated whenever the user switches into "Offline Mode" by selecting the corresponding menu item (File -> Work Offline in Firefox).

Additionally, this property should update whenever a browser is no longer capable of connecting to the network. According to the specification:

The navigator.onLine attribute must return false if the user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail)...

Firefox 2 updates this property when switching to/from the browser's Offline mode, and when losing/regaining network connectivity in Windows and Linux.

This property existed in older versions of Firefox and Internet Explorer (the specification based itself off of these prior implementations), so you can begin using it immediately. Network status autodetection was implemented in Firefox 2.

"online" and "offline" events

Firefox 3 introduces two new events: "online" and "offline". These two events are fired on the <body> of each page when the browser switches between online and offline mode. Additionally, the events bubble up from document.body, to document, ending at window. Both events are non-cancellable (you can't prevent the user from coming online, or going offline).

You can register listeners for these events in a few familiar ways:

  • using addEventListener on the window, document, or document.body
  • by setting the .ononline or .onoffline properties on document or document.body to a JavaScript Function object. (Note: using window.ononline or window.onoffline will not work for compatibility reasons.)
  • by specifying ononline="..." or onoffline="..." attributes on the <body> tag in the HTML markup.

Example

There's a simple test case that you can run to verify that the events are working. 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("Event: " + msg + "; status=" + 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>

References



{{ wiki.languages( { "es": "es/Eventos_online_y_offline", "fr": "fr/\u00c9v\u00e8nements_online_et_offline", "ja": "ja/Online_and_offline_events", "pl": "pl/Zdarzenia_online_i_offline", "pt": "pt/Eventos_online_e_offline" } ) }}

Revision Source

<p>{{template.Fx_minversion_header(3)}}
<a href="en/Firefox_3_for_developers">Firefox 3</a> implements <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#offline">Online/Offline events</a> from the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/">WHATWG Web Applications 1.0 specification</a>.
</p>
<h3 name="Overview"> Overview </h3>
<p>In order to build a good offline-capable web application, you need to know when your application is actually offline. Incidentally, you also need to know when your application has returned to an 'online' status again. Effectively, the requirements break down as such:
</p>
<ol><li> You need to know when the user comes back online, so that you can re-synchronize with the server.
</li><li> You need to know when the user is offline, so that you can be sure to queue your server requests for a later time.
</li></ol>
<p>It is this process that online/offline events help to trivialize.
</p><p>Your web application may also need to establish that certain documents be maintained in the offline resources cache.  To do so, include <code>LINK</code> elements in your <code>HEAD</code> section like this:
</p>
<pre class="eval"><span class="plain">&lt;link rel="offline-resource" href="myresource"&gt;</span>
</pre>
<p>When Firefox 3 or later processes the HTML, this will cause the resource referenced to be cached for offline use in a special offline resource cache.
</p>
<h3 name="API"> API </h3>
<h4 name="navigator.onLine"> <code>navigator.onLine</code> </h4>
<p><code><a href="en/DOM/window.navigator.onLine">navigator.onLine</a></code> is a property that maintains a <code>true</code>/<code>false</code> value (<code>true</code> for online, <code>false</code> for offline). This property is updated whenever the user switches into "Offline Mode" by selecting the corresponding menu item (File -&gt; Work Offline in Firefox).
</p><p>Additionally, this property should update whenever a browser is no longer capable of connecting to the network. According to the specification:
</p>
<blockquote cite="http://www.whatwg.org/specs/web-apps/current-work/#offline">
The <code>navigator.onLine</code> attribute must return false if the user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail)...
</blockquote>
<p>Firefox 2 updates this property when switching to/from the browser's Offline mode, and when losing/regaining network connectivity in Windows and Linux.
</p><p>This property existed in older versions of Firefox and Internet Explorer (the specification based itself off of these prior implementations), so you can begin using it immediately. Network status autodetection was implemented in Firefox 2.
</p>
<h4 name=".22online.22_and_.22offline.22_events"> "<code>online</code>" and "<code>offline</code>" events </h4>
<p><a href="en/Firefox_3">Firefox 3</a> introduces two new events: "<code>online</code>" and "<code>offline</code>". These two events are fired on the <code>&lt;body&gt;</code> of each page when the browser switches between online and offline mode. Additionally, the events bubble up from <code>document.body</code>, to <code>document</code>, ending at <code>window</code>. Both events are non-cancellable (you can't prevent the user from coming online, or going offline).
</p><p>You can register listeners for these events in a few familiar ways:
</p>
<ul><li> using <code><a href="en/DOM/element.addEventListener">addEventListener</a></code> on the <code>window</code>, <code>document</code>, or <code>document.body</code>
</li><li> by setting the <code>.ononline</code> or <code>.onoffline</code> properties on <code>document</code> or <code>document.body</code> to a JavaScript <code>Function</code> object. (<b>Note:</b> using <code>window.ononline</code> or <code>window.onoffline</code> will not work for compatibility reasons.)
</li><li> by specifying <code>ononline="..."</code> or <code>onoffline="..."</code> attributes on the <code>&lt;body&gt;</code> tag in the HTML markup.
</li></ul>
<h3 name="Example"> Example </h3>
<p>There's <a class="external" href="https://bugzilla.mozilla.org/attachment.cgi?id=220609">a simple test case</a> that you can run to verify that the events are working.
<span class="comment">XXX When mochitests for this are created, point to those instead and update this example -nickolay</span>
</p>
<pre class="eval"> &lt;!doctype html&gt;
 &lt;html&gt;
 &lt;head&gt;
   &lt;script&gt;
     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("Event: " + msg + "; status=" + condition + "\n"));
     }
     function loaded() {
       updateOnlineStatus("load");
       document.body.addEventListener("offline", function () {
         updateOnlineStatus("offline")
       }, false);
       document.body.addEventListener("online", function () {
         updateOnlineStatus("online")
       }, false);
     }
   &lt;/script&gt;
   &lt;style&gt;...&lt;/style&gt;
 &lt;/head&gt;
 &lt;body onload="loaded()"&gt;
   &lt;div id="status"&gt;&lt;p id="state"&gt;&lt;/p&gt;&lt;/div&gt;
   &lt;div id="log"&gt;&lt;/div&gt;
 &lt;/body&gt;
 &lt;/html&gt;
</pre>
<h3 name="References"> References </h3>
<ul><li> <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#offline">'Online/Offline events' section from the WHATWG Web Applications 1.0 Specification</a>
</li><li> <a class="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=336359">The bug tracking online/offline events implementation in Firefox</a> and a <a class="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=336682">follow-up</a>
</li><li> <a class="external" href="https://bugzilla.mozilla.org/attachment.cgi?id=220609">A simple test case</a>
</li><li> <a class="external" href="http://ejohn.org/blog/offline-events/">An explanation of Online/Offline events</a>
</li></ul>
<p><br>
</p><p><br>
</p>
<div class="noinclude">
</div>
{{ wiki.languages( { "es": "es/Eventos_online_y_offline", "fr": "fr/\u00c9v\u00e8nements_online_et_offline", "ja": "ja/Online_and_offline_events", "pl": "pl/Zdarzenia_online_i_offline", "pt": "pt/Eventos_online_e_offline" } ) }}
Revert to this revision