2009/dap/system-info battery-status.html,1.24,1.25

Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv12075

Modified Files:
	battery-status.html 
Log Message:
added an introduction

Index: battery-status.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/battery-status.html,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -d -r1.24 -r1.25
--- battery-status.html	8 Jun 2011 11:28:55 -0000	1.24
+++ battery-status.html	9 Jun 2011 11:55:38 -0000	1.25
@@ -71,6 +71,128 @@
       </p>
     </section>
     
+    <section class="informative">
+      <h2>Introduction</h2>
+      <p>
+        The Battery Status Event Specification defines a means for web
+        developers to programmatically determine the battery status of the
+        hosting device and whether the device is plugged in or not. Without
+        knowing the battery status of a device, a web developer must design
+        the web application with an assumption of sufficient battery level
+        for the task at hand. This means the battery of a device may exhaust
+        faster than desired because web developers are unable to make
+        decisions based on the battery status. With this knowledge of the
+        battery status, web developers are able to craft web content and
+        applications which are power efficient leading to improved user
+        experience.
+     </p>
+     <p>
+        The Battery Status Event can be used to defer or scale back work when
+        the device is not plugged in or is low on battery. An archetype of an
+        advanced web application, a web-based email client, may check the
+        server for new email every few seconds if the device is plugged in,
+        but do so less frequently if the device is not plugged in or is low on
+        battery. Another example is a web-based word processor which could
+        monitor the battery level and save changes before the battery runs
+        out to prevent data loss.
+      </p>
+      <p>
+        The following example shows how a web-based email client could check
+        for new emails every second without knowledge of the battery status:
+      </p>
+      <pre class='example sh_javascript'>
+        &lt;!DOCTYPE html&gt;
+        &lt;html&gt;
+        &lt;head&gt;
+          &lt;title&gt;Email Client&lt;/title&gt;
+          &lt;script&gt;
+            var mail = {
+              INTERVAL_DEFAULT: 1000,
+              interval_current: null,
+              timer: 0,
+
+              check: function () {
+                console.log('Checking the server for new emails using ' +
+                  'an interval of ' + (mail.interval_current/1000) + ' s.');
+              }
+            };
+
+            window.onload = function () {
+              var interval = (!mail.interval_current) ?
+                mail.INTERVAL_DEFAULT : mail.interval_current;
+              
+              mail.timer = setInterval(function () {
+                mail.check();
+              }, interval);
+              
+              mail.interval_current = interval;
+            };
+          &lt;/script&gt;
+        &lt;/head&gt;
+        &lt;body&gt;&lt;/body&gt;
+        &lt;/html&gt;
+
+      </pre>
+      <p>
+        The script will always check for emails every second, even if the
+        battery level is critically low and the device is not plugged in.
+        This is an example of poor resource management.
+      </p>
+      <p>
+        Using the <a>BatteryStatusEvent</a> interface, the web application is,
+        for example, able to throttle checking for emails if the device is not
+        plugged in and the battery level is below 10%:
+      </p>
+      <pre class='example sh_javascript'>
+        &lt;!DOCTYPE html&gt;
+        &lt;html&gt;
+        &lt;head&gt;
+          &lt;title&gt;Battery-aware Email Client&lt;/title&gt;
+          &lt;script&gt;
+            var mail = {
+              INTERVAL_LOW_BATTERY: 1000 * 60 * 10,
+              INTERVAL_DEFAULT: 1000,
+              interval_current: null,
+              timer: 0,
+
+              check: function () {
+                console.log('Checking the server for new emails using ' +
+                  'an interval of ' + (mail.interval_current/1000) + ' s.');
+              }
+            };
+
+            window.onload = function () {
+              var interval = (!mail.interval_current) ?
+                mail.INTERVAL_DEFAULT : mail.interval_current;
+              
+              mail.timer = setInterval(function () {
+                mail.check();
+              }, interval);
+              
+              mail.interval_current = interval;
+            };
+
+            window.onbatterystatus = function (battery) {
+              var interval = (!battery.isPlugged && battery.level &lt; 10) ?
+                mail.INTERVAL_LOW_BATTERY : mail.INTERVAL_DEFAULT;
+
+              if (interval !== mail.interval_current) {
+                clearTimeout(mail.timer);
+
+                mail.timer = setInterval(function () {
+                  mail.check();
+                }, interval);
+
+                mail.interval_current = interval;
+              }
+            };
+          &lt;/script&gt;
+        &lt;/head&gt;
+        &lt;body&gt;&lt;/body&gt;
+        &lt;/html&gt;
+      </pre>
+    </section>
+    
     <section id='conformance'>
       <p>
         This specification defines conformance criteria that apply to a single
@@ -226,9 +348,9 @@
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-window.addEventListener('batterystatus', function (event) {
-  console.log(event.level);
-}, true);
+          window.addEventListener('batterystatus', function (event) {
+            console.log(event.level);
+          }, true);
         </pre>
       </div>
       <p>
@@ -236,9 +358,9 @@
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-window.onbatterystatus = function (event) {
-  console.log(event.level);
-};
+          window.onbatterystatus = function (event) {
+            console.log(event.level);
+          };
         </pre>
       </div>
       <p>
@@ -249,12 +371,12 @@
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-var handler = function (event) {
-  console.log(event.level);
-  window.removeEventListener('batterystatus', handler, true);
-};
+          var handler = function (event) {
+            console.log(event.level);
+            window.removeEventListener('batterystatus', handler, true);
+          };
 
-window.addEventListener('batterystatus', handler, true);
+          window.addEventListener('batterystatus', handler, true);
         </pre>
       </div>
       <p>
@@ -262,10 +384,10 @@
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-window.onbatterystatus = function (event) {
-  console.log(event.level);
-  window.onbatterystatus = null;
-};
+          window.onbatterystatus = function (event) {
+            console.log(event.level);
+            window.onbatterystatus = null;
+          };
         </pre>
       </div>
       <p>
@@ -276,23 +398,23 @@
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-&lt;!DOCTYPE html&gt;
-&lt;html&gt;
-&lt;head&gt;
-  &lt;title&gt;Battery Status Event Example&lt;/title&gt;
-  &lt;script&gt;
-    function update(battery) {
-      document.querySelector('#plugged').textContent =
-        battery.isPlugged ? 'plugged' : 'not plugged';
-      document.querySelector('#level').textContent = battery.level;
-    }
-  &lt;/script&gt;
-&lt;/head&gt;
-&lt;body onbatterystatus="update(this)"&gt;
-&lt;div id="plugged"&gt;(plugged state unknown)&lt;/div&gt;
-&lt;div id="level"&gt;(battery level unknown)&lt;/div&gt;
-&lt;/body&gt;
-&lt;/html&gt;
+          &lt;!DOCTYPE html&gt;
+          &lt;html&gt;
+          &lt;head&gt;
+            &lt;title&gt;Battery Status Event Example&lt;/title&gt;
+            &lt;script&gt;
+              function update(battery) {
+                document.querySelector('#plugged').textContent =
+                  battery.isPlugged ? 'plugged' : 'not plugged';
+                document.querySelector('#level').textContent = battery.level;
+              }
+            &lt;/script&gt;
+          &lt;/head&gt;
+          &lt;body onbatterystatus="update(this)"&gt;
+            &lt;div id="plugged"&gt;(plugged state unknown)&lt;/div&gt;
+            &lt;div id="level"&gt;(battery level unknown)&lt;/div&gt;
+          &lt;/body&gt;
+          &lt;/html&gt;
         </pre>
       </div>
     </section>
@@ -301,7 +423,14 @@
       <h2>Acknowledgements</h2>
       <p>
         Many thanks to the people behind the System Information API and Device
-        Orientation Event Specification for inspiration. 
+        Orientation Event Specification for inspiration. Also thanks to the
+        nice folks bringing us the Page Visibility specification, which
+        motivated the editor of this specification to write the introduction
+        chapter discussing some real-world high value use cases that apply
+        equally to this specification. Special thanks to all the participants
+        of the Device APIs Working Group who have sent in substantial feedback
+        and comments, and made the Web a better place for everyone while doing
+        so.
       </p>
     </section>
   </body>

Received on Thursday, 9 June 2011 11:55:42 UTC