- From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 09 Jun 2011 11:55:40 +0000
- To: public-dap-commits@w3.org
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'>
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Email Client</title>
+ <script>
+ 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;
+ };
+ </script>
+ </head>
+ <body></body>
+ </html>
+
+ </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'>
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Battery-aware Email Client</title>
+ <script>
+ 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 < 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;
+ }
+ };
+ </script>
+ </head>
+ <body></body>
+ </html>
+ </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'>
-<!DOCTYPE html>
-<html>
-<head>
- <title>Battery Status Event Example</title>
- <script>
- function update(battery) {
- document.querySelector('#plugged').textContent =
- battery.isPlugged ? 'plugged' : 'not plugged';
- document.querySelector('#level').textContent = battery.level;
- }
- </script>
-</head>
-<body onbatterystatus="update(this)">
-<div id="plugged">(plugged state unknown)</div>
-<div id="level">(battery level unknown)</div>
-</body>
-</html>
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Battery Status Event Example</title>
+ <script>
+ function update(battery) {
+ document.querySelector('#plugged').textContent =
+ battery.isPlugged ? 'plugged' : 'not plugged';
+ document.querySelector('#level').textContent = battery.level;
+ }
+ </script>
+ </head>
+ <body onbatterystatus="update(this)">
+ <div id="plugged">(plugged state unknown)</div>
+ <div id="level">(battery level unknown)</div>
+ </body>
+ </html>
</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