HTML5

SHARE

Working with the Battery Status API in HTML5 Web Applications

Written By

Vipul Patel

Apr 17, 2014

Web pages today aren

’

t just static files. There is increased client-side processing in today

’

s rich web apps. This has resulted in increasing power consumption by browsers. As internet gets increasingly consumed through mobile devices, it is important for web developers to design their web pages with the consideration that the device rendering the HTML might be power constrained.

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
The HTML5 specification says…
Hands On
Summary
About the author
References

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.

[NoInterfaceObject]

interface NavigatorBattery {

    readonly attribute BatteryManager battery;

};

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>

<h1>Battery API demo</h1>

<p>Demo showing battery API in action (does not work on all browsers)</p>

</header>

<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>

// 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