Events

Events

Cordova lifecycle events.

Event Types

Events added by BatteryStatus-plugin

Events added by Network-plugin


deviceready

The event fires when Cordova is fully loaded.

document.addEventListener("deviceready", yourCallbackFunction, false);

Details

This event is essential to any application. It signals that Cordova's device APIs have loaded and are ready to access.

Cordova consists of two code bases: native and JavaScript. While the native code loads, a custom loading image displays. However, JavaScript only loads once the DOM loads. This means your web application may potentially call a Cordova JavaScript function before the corresponding native code is available.

The deviceready event fires once Cordova has fully loaded. Once the event fires, you can safely make calls to Cordova APIs. Applications typically attach an event listener with document.addEventListener once the HTML document's DOM has loaded.

The deviceready event behaves somewhat differently from others. Any event handler registered after the deviceready event fires has its callback function called immediately.

Quick Example

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
    // Now safe to use device APIs
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Device Ready Example</title>

    <script type="text/javascript" charset="utf-8" src="/cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="/components/steroids-js/steroids.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        // Now safe to use device APIs
    }

    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

pause

The event fires when an application is put into the background.

document.addEventListener("pause", yourCallbackFunction, false);

Details

The pause event fires when the native platform puts the application into the background, typically when the user switches to a different application.

Applications typically should use document.addEventListener to attach an event listener once the deviceready event fires.

Quick Example

document.addEventListener("pause", onPause, false);

function onPause() {
    // Handle the pause event
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Pause Example</title>

    <script type="text/javascript" charset="utf-8" src="/cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="/components/steroids-js/steroids.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        document.addEventListener("pause", onPause, false);
    }

    // Handle the pause event
    //
    function onPause() {
    }

    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

iOS Quirks

In the pause handler, any calls to the Cordova API or to native plugins that go through Objective-C do not work, along with any interactive calls, such as alerts or console.log(). They are only processed when the app resumes, on the next run loop.


resume

The event fires when an application is retrieved from the background.

document.addEventListener("resume", yourCallbackFunction, false);

Details

The resume event fires when the native platform pulls the application out from the background.

Applications typically should use document.addEventListener to attach an event listener once the deviceready event fires.

Quick Example

document.addEventListener("resume", onResume, false);

function onResume() {
    // Handle the resume event
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Resume Example</title>

    <script type="text/javascript" charset="utf-8" src="/cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="/components/steroids-js/steroids.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        document.addEventListener("resume", onResume, false);
    }

    // Handle the resume event
    //
    function onResume() {
    }

    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

iOS Quirks

Any interactive functions called from a pause event handler execute later when the app resumes, as signaled by the resume event. These include alerts, console.log(), and any calls from plugins or the Cordova API, which go through Objective-C.

  • active event

    The iOS-specific active event is available as an alternative to resume, and detects when users disable the Lock button to unlock the device with the app running in the foreground. If the app (and device) is enabled for multi-tasking, this is paired with a subsequent resume event, but only under iOS 5. In effect, all locked apps in iOS 5 that have multi-tasking enabled are pushed to the background. For apps to remain running when locked under iOS 5, disable the app's multi-tasking by setting UIApplicationExitsOnSuspend to YES. To run when locked on iOS 4, this setting does not matter.

  • resume event

    When called from a resume event handler, interactive functions such as alert() need to be wrapped in a setTimeout() call with a timeout value of zero, or else the app hangs. For example:

    document.addEventListener("resume", onResume, false);
    function onResume() {
       setTimeout(function() {
              // TODO: do your thing!
            }, 0);
    }
    

online

This event fires when an application goes online, and the device becomes connected to the Internet.

document.addEventListener("online", yourCallbackFunction, false);

Details

The online event fires when a previously unconnected device receives a network connection to allow an application access to the Internet. It relies on the same information as the Connection API, and fires when the value of connection.type becomes NONE.

Applications typically should use document.addEventListener to attach an event listener once the deviceready event fires.

Quick Example

document.addEventListener("online", onOnline, false);

function onOnline() {
    // Handle the online event
}

iOS Quirks

During initial startup, the first online event (if applicable) takes at least a second to fire, prior to which connection.type is UNKNOWN.


offline

The event fires when an application goes offline, and the device is not connected to the Internet.

document.addEventListener("offline", yourCallbackFunction, false);

Details

The offline event fires when a previously connected device loses a network connection so that an application can no longer access the Internet. It relies on the same information as the Connection API, and fires when the connection.type changes from NONE to any other value.

Applications typically should use document.addEventListener to attach an event listener once the deviceready event fires.

Quick Example

document.addEventListener("offline", onOffline, false);

function onOffline() {
    // Handle the offline event
}

iOS Quirks

During initial startup, the first offline event (if applicable) takes at least a second to fire.


backbutton

The event fires when the user presses the back button.

document.addEventListener("backbutton", yourCallbackFunction, false);

Details

To override the default back-button behavior, register an event listener for the backbutton event, typically by calling document.addEventListener once you receive the deviceready event. It is no longer necessary to call any other method to override the back-button behavior.

Supported Platforms

  • Android

Quick Example

document.addEventListener("backbutton", onBackKeyDown, false);

function onBackKeyDown() {
    // Handle the back button
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Back Button Example</title>

    <script type="text/javascript" charset="utf-8" src="/cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="/components/steroids-js/steroids.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        // Register the event listener
        document.addEventListener("backbutton", onBackKeyDown, false);
    }

    // Handle the back button
    //
    function onBackKeyDown() {
    }

    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

batterycritical

The event fires when the percentage of battery charge has reached the critical battery threshold. The value is device-specific.

The batterycritical handler is passed an object that contains two properties:

  • level: The percentage of battery charge (0-100). (Number)

  • isPlugged: A boolean that indicates whether the device is plugged in. (Boolean)

Applications typically should use window.addEventListener to attach an event listener once the deviceready event fires.

Example

window.addEventListener("batterycritical", onBatteryCritical, false);

function onBatteryCritical(info) {
    // Handle the battery critical event
    alert("Battery Level Critical " + info.level + "%\nRecharge Soon!");
}

batterylow

The event fires when the percentage of battery charge has reached the low battery threshold, device-specific value.

The batterylow handler is passed an object that contains two properties:

  • level: The percentage of battery charge (0-100). (Number)

  • isPlugged: A boolean that indicates whether the device is plugged in. (Boolean)

Applications typically should use window.addEventListener to attach an event listener once the deviceready event fires.

Example

window.addEventListener("batterylow", onBatteryLow, false);

function onBatteryLow(info) {
    // Handle the battery low event
    alert("Battery Level Low " + info.level + "%");
}

batterystatus

This event fires when the percentage of battery charge changes by at least 1 percent, or if the device is plugged in or unplugged.

The battery status handler is passed an object that contains two properties:

  • level: The percentage of battery charge (0-100). (Number)

  • isPlugged: A boolean that indicates whether the device is plugged in. (Boolean)

Applications typically should use window.addEventListener to attach an event listener once the deviceready event fires. e.g.:

Example

window.addEventListener("batterystatus", onBatteryStatus, false);

function onBatteryStatus(info) {
    // Handle the online event
    console.log("Level: " + info.level + " isPlugged: " + info.isPlugged);
}

menubutton

The event fires when the user presses the menu button.

document.addEventListener("menubutton", yourCallbackFunction, false);

Details

Applying an event handler overrides the default menu button behavior.

Applications typically should use document.addEventListener to attach an event listener once the deviceready event fires.

Supported Platforms

  • Android

Quick Example

document.addEventListener("menubutton", onMenuKeyDown, false);

function onMenuKeyDown() {
    // Handle the back button
}

Full Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Menu Button Example</title>

    <script type="text/javascript" charset="utf-8" src="/cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="/components/steroids-js/steroids.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        // Register the event listener
        document.addEventListener("menubutton", onMenuKeyDown, false);
    }

    // Handle the menu button
    //
    function onMenuKeyDown() {
    }

    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

searchbutton

The event fires when the user presses the search button on Android.

document.addEventListener("searchbutton", yourCallbackFunction, false);

Details

If you need to override the default search button behavior on Android you can register an event listener for the 'searchbutton' event.

Applications typically should use document.addEventListener to attach an event listener once the deviceready event fires.

Supported Platforms

  • Android

Quick Example

document.addEventListener("searchbutton", onSearchKeyDown, false);

function onSearchKeyDown() {
    // Handle the search button
}

Full Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Search Button Example</title>

    <script type="text/javascript" charset="utf-8" src="/cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="/components/steroids-js/steroids.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        // Register the event listener
        document.addEventListener("searchbutton", onSearchKeyDown, false);
    }

    // Handle the search button
    //
    function onSearchKeyDown() {
    }

    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>