If the web application can be made aware of the battery status of the device, the web developers can author the web application such that it can stop or reduce the power-intensive processing if the device is low on battery.
With this scenario in mind, the HTML5 specification has provided API for determining the battery status. With the knowledge of the device’s battery status, the web application can effectively craft the content and optimized experience.
What are the uses of battery status API
- Email applications can reduce the frequency for polling for email updates if the determine that the device’s battery is low/critical.
- Client-site JavaScript processing can be reduced when battery is low.
- A word processing web application can increase the frequency of automatically saving the content if it determines that the batter us low.
- Switch to a less power-hungry CSS theme for the styling of the web page.
- Avoiding network calls for downloading images.
- Offline storing of web application data.
The HTML5 specification says…
The HTML5 specification for battery status is available at http://www.w3.org/TR/battery-status/.
BatteryManager Interface
The BatteryManager interface is specified as below.
[NoInterfaceObject]
interface BatteryManager : EventTarget {
readonly attribute boolean charging;
readonly attribute double chargingTime;
readonly attribute double dischargingTime;
readonly attribute double level;
[TreatNonCallableAsNull]
attribute Function? onchargingchange;
[TreatNonCallableAsNull]
attribute Function? onchargingtimechange;
[TreatNonCallableAsNull]
attribute Function? ondischargingtimechange;
[TreatNonCallableAsNull]
attribute Function? onlevelchange;
};
The BatteryManager interface exposes 4 properties
charging – boolean – represents if the system’s battery is charging
chargingTime – double – represents the time remaining (in seconds) for the battery to be fully charged.
dischargingTime – double – represents the time remaining (in seconds) for the battery to be completely discharged and the system is about to be suspended.
level – double – represents the current battery level, min 0.0, max 1.0.
It also specifies 4 events.
onchargingchange – Event fired when charging activity changes.
onchargingtimechange –Event fired when the time remaining to completely charge the device changes.
ondischargingtimechange –Event fired when the time remaining to completely discharge the device changes.
onlevelchange – Event fired when the level changes.
NavigatorBattery
The HTML5 specification outlines that all kinds of Navigator type implement the NavigatorBattery interface, which is defined as below.
This means that access to the battery is made by calling “navigator.battery”.
Hands On
Here is a snippet which shows how we can use the battery API in HTML5 web pages. Note that the API is not currently implemented by any modern browser, so these samples might not work.
<!DOCTYPE html>
<html>
<head>
<!—->
</head>
<body>
<header>
<h1>Battery API demo</h1>
<p>Demo showing battery API in action (does not work on all browsers)</p>
</header>
<footer>
<h1></h1>
<p>HTML Goodies</p>
</footer>
<div id=”charging”>(charging state unknown)</div>
<div id=”level”>(battery level unknown)</div>
<div id=”chargingTime“>(charging time unknown)</div>
<div id=”dischargingTime“>(discharging time unknown)</div>
<script>
// Get the battery object
var battery = navigator.battery;
//Trap the charging change event and update the element “charging” with whether the device is charging or not.
battery.onchargingchange = function () {
document.querySelector(‘#charging’).textContent = battery.charging ? ‘charging‘ : ‘not charging’;
};
//Trap the level change event and update the element “level” with the current device level.
battery.onlevelchange = function () {
document.querySelector(‘#level’).textContent = battery.level;
};
//Trap the discharging change event and update the element “dischargingTime” with the time remaining to completelt discharge the device.
battery.ondischargingtimechange = function () {
document.querySelector(‘#dischargingTime‘).textContent = battery.dischargingTime / 60;
};
//Trap the charging change event and update the element “chargingTime” with the time remaining to completely charge the device.
battery.onchargingtimechange = function () {
document.querySelector(‘#chargingTime‘).textContent = battery.chargingTime / 60;
}
</script>
</body>
</html>
If the browser supported battery API, it will show the battery information.
Some browsers have implemented the support for battery API differently. To work with this, you can declare the battery object as below as use it today.
var battery = navigator.battery || navigator.webkitBattery || navigator.mozBattery || navigator.msBattery || null;
Summary
In this article, we learned about the battery API. I hope you have found this information useful.
About the author
Vipul Patel is a Program Manager currently working at Amazon Corporation. He has formerly worked at Microsoft in the Lync team and in the .NET team (in the Base Class libraries and the Debugging and Profiling team). He can be reached at vipul.patel@hotmail.com
References
http://www.w3.org/TR/battery-status/