Events

Events

PhoneGap lifecycle events.

Event Types


deviceready

This is an event that fires when PhoneGap is fully loaded.

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

Details

This is a very important event that every PhoneGap application should use.

PhoneGap consists of two code bases: native and JavaScript. While the native code is loading, a custom loading image is displayed. However, JavaScript is only loaded once the DOM loads. This means your web application could, potentially, call a PhoneGap JavaScript function before it is loaded.

The PhoneGap deviceready event fires once PhoneGap has fully loaded. After the device has fired, you can safely make calls to PhoneGap function.

Typically, you will want to attach an event listener with document.addEventListener once the HTML document's DOM has loaded.

Supported Platforms

Quick Example

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

function onDeviceReady() {
    // Now safe to use the PhoneGap API
}

Full Example

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

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        // Now safe to use the PhoneGap API
    }

    </script>
  </head>
  <body>
  </body>
</html>

BlackBerry (OS 4.6) Quirks

Custom events are not supported in the RIM BrowserField (web browser view), so the deviceready event will never fire.

A workaround is to manually query PhoneGap.available until PhoneGap has fully loaded.

function onLoad() {
    // BlackBerry OS 4 browser does not support events.
    // So, manually wait until PhoneGap is available.
    //
    var intervalID = window.setInterval(
      function() {
          if (PhoneGap.available) {
              window.clearInterval(intervalID);
              onDeviceReady();
          }
      },
      500
    );
}

function onDeviceReady() {
    // Now safe to use the PhoneGap API
}

pause

This is an event that fires when a PhoneGap application is put into the background.

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

Details

PhoneGap consists of two code bases: native and JavaScript. While the native code puts the application into the background the pause event is fired.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

Quick Example

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

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

Full Example

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

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        document.addEventListener("pause", onPause, false);
    }

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

    </script>
  </head>
  <body>
  </body>
</html>

iOS Quirks

In the pause handler, any calls that go through Objective-C will not work, nor will any calls that are interactive, like alerts. This means that you cannot call console.log (and its variants), or any calls from Plugins or the PhoneGap API. These will only be processed when the app resumes (processed on the next run-loop).


resume

This is an event that fires when a PhoneGap application is retrieved from the background.

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

Details

PhoneGap consists of two code bases: native and JavaScript. While the native code pulls the application from the background the resume event is fired.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

Quick Example

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

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

Full Example

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

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        document.addEventListener("resume", onResume, false);
    }

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

    </script>
  </head>
  <body>
  </body>
</html>

online

This is an event that fires when a PhoneGap application is online (connected to the Internet).

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

Details

When the application's network connection changes to being online, the online event is fired.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

Quick Example

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

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

Full Example

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

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        document.addEventListener("online", onOnline, false);
    }

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

    </script>
  </head>
  <body>
  </body>
</html>

iOS Quirks

During initial startup, the first online event (if applicable) will take at least a second to fire.


offline

This is an event that fires when a PhoneGap application is offline (not connected to the Internet).

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

Details

When the application's network connection changes to being offline, the offline event is fired.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

Quick Example

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

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

Full Example

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

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        document.addEventListener("offline", onOffline, false);
    }

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

    </script>
  </head>
  <body>
  </body>
</html>

iOS Quirks

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


backbutton

This is an event that fires when the user presses the back button on Android.

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

Details

If you need to over ride the default back button behaviour on Android you can register and event listener for the 'backbutton' event. It is no longer necessary to call any other method to over ride the back button behaviour. Now, you only need to register an event listener for 'backbutton'.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

Quick Example

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

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

Full Example

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

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        // Register the event listener
        document.addEventListener("backbutton", onBackKeyDown, false);
    }

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

    </script>
  </head>
  <body>
  </body>
</html>

menubutton

This is an event that fires when the user presses the menu button on Android.

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

Details

If you need to over ride the default menu button behaviour on Android you can register and event listener for the 'menubutton' event.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

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>PhoneGap Device Ready Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    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

This is an event that fires when the user presses the search button on Android.

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

Details

If you need to over ride the default search button behaviour on Android you can register and event listener for the 'searchbutton' event.

Typically, you will want to attach an event listener with document.addEventListener once you receive the PhoneGap 'deviceready' event.

Supported Platforms

Quick Example

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

function onSearchKeyDown() {
    // 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>PhoneGap Device Ready Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Call onDeviceReady when PhoneGap is loaded.
    //
    // At this point, the document has loaded but phonegap-1.0.0.js has not.
    // When PhoneGap is loaded and talking with the native device,
    // it will call the event `deviceready`.
    // 
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
    //
    function onDeviceReady() {
        // Register the event listener
        document.addEventListener("searchbutton", onSearchKeyDown, false);
    }

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

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