Skip to content

February 14, 2012

1

PhoneGap Network Connection and Events

by Colin

In this tutorial we will take a look at the PhoneGap connection object which gives access to the device’s cellular and wifi connection information. We will use this feature to check what type of connection we have active on our device. Also we will take a look at some of the event types for Android and iOS provided by phonegap.

End result:



Download the sources and setup the project.

Open index.html and let’s look at the code:

[html]
<!– Start of Network page –>
<div data-role="page">
<div data-role="header" data-position="fixed">
<h1>Network & Events</h1>
</div>
<div data-role="content">
<div id="netowrk">
<h3>Check network connection type:</h3>
<a data-role="button" id="checkConnection" data-theme="e">Check Network</a>
<h3>Online / Offline Section</h3>
<p id="online">Example content that is displayed when the device <strong>has</strong> Internet connectivity.</p>
<p id="offline">Example content that is displayed when the device <strong>doesn’t have</strong> Internet connectivity.</p>
</div>
</div>
<div data-role="footer" data-position="fixed" id="footer">
<p>Footer</p>
</div>
</div>
<!– /Network page –>
[/html]

We have the basic structure of a page: header, content and footer. In the content area we have a button that displays an alert containing information about our current active network such as 3G, wifi and so on. This is done by the checkConnection() function:

[js]
function checkConnection() {
var networkState = navigator.network.connection.type;

var states = {};
states[Connection.UNKNOWN] = ‘Unknown connection';
states[Connection.ETHERNET] = ‘Ethernet connection';
states[Connection.WIFI] = ‘WiFi connection';
states[Connection.CELL_2G] = ‘Cell 2G connection';
states[Connection.CELL_3G] = ‘Cell 3G connection';
states[Connection.CELL_4G] = ‘Cell 4G connection';
states[Connection.NONE] = ‘No network connection';

alert(‘Connection type: ‘+ states[networkState]);
}
[/js]

Here we have the network states and with the help of navigator.network.connection.type we can figure out whether the device has the WiFi turned on or off or if the device has the 3G turned on or off. If you try this on the simulator it will probably tell you it’s running on 3g (by default) but you can activate the WiFi and run the application again and see the result. It’s a good feature to have if your application is web based and it’s useful to know if the device is connected to a WiFi network or if it’s running on 3G, specially if the user wants to download some files which have big size it would be nice to alert him if he’s running on 3G to switch to a WiFi connection or just alert him that the application requires an internet connection for some functionalities.

That sums up about the network connection component. Now let’s take a look at the events section

In the events section I exampled the use of online and offline events. I consider this to be a very important feature if you have an application that requires internet connectivity at some point. Below this there is a list with most of the PhoneGap events supported for Android and iOS devices.

In order to determine if the device is online or offline we add the event listeners to our custom script (script.js):

[js]
document.addEventListener("offline", onOffline, false);
document.addEventListener("online", onOnline, false);
[/js]

When we determine if the device is offline the onOffline() function handles this event.

[js]
function onOffline() {
// Handle the offline event
alert("You are offline!");
var offline = $(‘#offline’);
var online = $(‘#online’);
offline.show();
online.hide();
}
[/js]

If the device is online the onOnline() function handles the event.

[js]
function onOnline() {
// Handle the online event
alert("You are online!");
var online = $(‘#online’);
var offline = $(‘#offline’);
online.show();
offline.hide();
}
[/js]

So what we do is check if the device is connected to the internet or not and we display content according to the connectivity.

[html]
<h3>Online / Offline Section</h3>
<p id="online">Example content that is displayed when the device <strong>has</strong> Internet connectivity.</p>
<p id="offline">Example content that is displayed when the device <strong>doesn’t have</strong> Internet connectivity.</p>
[/html]

That’s all. Below you have a list with the events supported by PhoneGap:

deviceready

For web developers this is the equivalent of jQuery’s $(document).ready() function for phonegap. It fires when PhoneGap is fully loaded.

[js]
document.addEventListener("deviceready", onDeviceReady, false);

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

pause

This event fires when the applications is put into the background.

[js]
document.addEventListener("pause", onPause, false);

function onPause() {
// Handle the pause event
}
[/js]

resume

This event fires when the apllication is retrieved from the background.

[js]
document.addEventListener("resume", onResume, false);

function onResume() {
// Handle the resume event
}
[/js]

online

This event fires when the application has connectivity to the Internet.

[js]
document.addEventListener("online", onOnline, false);

function onOnline() {
// Handle the online event
}
[/js]

offline

This event fires when the application has no conectivity to the Internet.

[js]
document.addEventListener("offline", onOffline, false);

function onOffline() {
// Handle the offline event
}
[/js]

backbutton

This event is supported on Android or BlackBerry platforms. It fires when the backbutton is pressed. So if you need to override the backbutton functionality you just have to add an event listener.

[js]
document.addEventListener("backbutton", onBackKeyDown, false);

function onBackKeyDown() {
// Handle the back button
}
[/js]

batterycritical

This event fires when the application detects the percentage of battery has reached a critical level. The value is device specific.

[js]
window.addEventListener("batterycritical", onBatteryCritical, false);

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

batterylow

This event fires when the application detects the percentage of battery has reached a low level. This value is device specific.

[js]
window.addEventListener("batterylow", onBatteryLow, false);

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

batterystatus

This event fires when the application detects a change in the battery status, at least 1 percent.

[js]
window.addEventListener("batterystatus", onBatteryStatus, false);

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

menubutton

This event fires when the menu button is pressed. Works on Android and BlackBerry platforms. It’s useful if you need to change it’s functionality, just add the event listener.

[js]
document.addEventListener("menubutton", onMenuKeyDown, false);

function onMenuKeyDown() {
// Handle the back button
}
[/js]

searchbutton

This event fires when the search button is pressed, it only works on the Android platform.

[js]
document.addEventListener("searchbutton", onSearchKeyDown, false);

function onSearchKeyDown() {
// Handle the search button
}
[/js]

startcallbutton

This event fires when the start call button is pressed, it works only on the BlackBerry platform.

[js]
document.addEventListener("startcallbutton", onStartCallKeyDown, false);

function onStartCallKeyDown() {
// Handle the start call button
}
[/js]

endcallbutton

This event fires when the end call button is pressed, it works only on the BlackBerry platform.

[js]
document.addEventListener("endcallbutton", onEndCallKeyDown, false);

function onEndCallKeyDown() {
// Handle the end call button
}
[/js]

volumedownbutton

This event fires when the volume down button is pressed, it works only on the BlackBerry platform.

[js]
document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);

function onVolumeDownKeyDown() {
// Handle the volume down button
}
[/js]

volumeupbutton

This event fires when the volume up button is pressed, it works only on the BlackBerry platform.

[js]
document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);

function onVolumeUpKeyDown() {
// Handle the volume up button
}
[/js]

Good luck with mobile Apps development!

Read more from Mobile

Leave a Reply

required
required

Note: HTML is allowed. Your email address will never be published.

Subscribe to comments