21. Notification
The PhoneGap Notification API provides methods that allow an application to provide feedback to a user visually (through pop-up alerts) and through tactile or audible feedback. The methods supported by this API are as follows:
• notification.alert
• notification.confirm
• notification.beep
• notification.vibrate
Visual Alerts (Alert and Confirm)
The alert and confirm methods are each essentially extended versions of the standard JavaScript alert function. The JavaScript alert method, which works just fine in PhoneGap applications, takes a single parameter, which is the text of the message displayed on the screen, as shown in the following example:
alert("You clicked the Click Me button.");
This code generates the pop-up dialog shown in Figure 21-1.
Figure 21-1 A standard JavaScript alert
The PhoneGap alert and confirm functions allow a program to control not only the message being displayed but also the title associated with the pop-up dialog, the text displayed on the dialog’s button(s), and the function that’s executed when the user clicks a button in the pop-up. The difference between alert and confirm is the number of buttons displayed in the dialog; alert displays a single button, and confirm can display one or more buttons.
The following is an example of how to call the PhoneGap alert function:
navigator.notification.alert(message_text, callback_function,
"title", "button_text");
The parameters passed to the function are described here:
• message_text: The message text that appears between the title and the button.
• callback_function: The function that is executed when the user clicks the button on the dialog.
• title: (Optional.) The text that appears on the top of the pop-up dialog.
• button_text: (Optional.) The text that appears on the button. If no value is provided, it will default to OK.
The following code shows an example of how to use the PhoneGap alert method:
navigator.notification.alert("Figure 21-2", onDoAlert,
"Sample Alert", "Click Me!");
This will generate the pop-up dialog shown in Figure 21-2 and execute the onDoAlert function after the user clicks the button.
Figure 21-2 PhoneGap alert on an Android device
To skip executing a function when the user clicks the button, simply pass in a null for the function name, as shown in the following example:
navigator.notification.alert("Figure 21-2", null,
"Sample Alert", "Click Me!");
The confirm function operates exactly the same as alert; the only difference is in the button_text parameter passed to the function. Instead of a single text value, confirm expects a comma-separated list of values, as shown here:
navigator.notification.confirm(message_text, callback_
function, "title", "button_text_array");
If no button values are provided, the function will default to using OK and Cancel.
The following code will generate the pop-up dialog shown in Figure 21-3 and execute the onDoConfirm function after the user clicks either of the buttons:
navigator.notification.confirm("Figure 21-3", onDoConfirm,
"Sample Confirmation", "Yes, No");
Figure 21-3 PhoneGap confirm on an Android device
When the onDoConfirm function is called by confirm, it passes in a button variable that represents the number of the button clicked by the application user. As shown in the following example, a value of 1 is assigned to the first button, 2 to the second, and so on:
function onDoConfirm(btnNum) {
if(btnNum == "1") {
alert("Thanks for saying yes!");
} else {
alert("Too bad, you said no.");
}
}
Beep
To play the mobile device’s default beep tone, execute the following code:
navigator.notification.beep(beepCount);
The beepCount parameter is a numeric value that defines the number of times the beep should play.
Vibrate
To cause the mobile device to vibrate, execute the following code:
navigator.notification.vibrate(vibeDuration);
The vibeDuration parameter is a numeric value that refers to the number of milliseconds the device should vibrate. A value of 1000 equals one second, 500 is half a second, and so on. To make an application vibrate, pause, and then vibrate again, you will have to manually call vibrate several times and force the required wait between calls; there is no repeat value that can be passed to the vibrate function.
Notification in Action
Example 21-1 shows an application that highlights each of the supported functions in the PhoneGap Notification API.
<!DOCTYPE html>
<html>
<head>
<title>Example 21-1</title>
<meta name="viewport" content="width=device-width,
height=device-height initial-scale=1.0,
maximum-scale=1.0, user-scalable=no;" />
<meta http-equiv="Content-type" content="text/html;
charset=utf-8">
<link rel="stylesheet" href="jquery.mobile1.0b3.min.css" />
<script type="text/javascript" charset="utf-8"
src="jquery1.6.4.min.js"></script>
<script type="text/javascript" charset="utf-8"
src="jquery.mobile1.0b3.min.js"></script>
<script type="text/javascript" charset="utf-8"
src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
function onBodyLoad() {
//alert("onBodyLoad");
document.addEventListener("deviceready",
onDeviceReady, false);
}
function onDeviceReady() {
//Nothing to do here really
alert("onDeviceReady");
}
function doAlert() {
msgText = document.getElementById('msgText').value;
navigator.notification.alert(msgText, onDoAlert,
"Sample Alert", "Click Me!");
}
function onDoAlert() {
alert("You clicked the Click Me button.");
}
function doConfirm() {
msgText = document.getElementById('msgText').value;
navigator.notification.confirm(msgText, onDoConfirm,
"Sample Confirmation", "Yes, No");
}
function onDoConfirm(btnNum) {
if(btnNum == "1") {
alert("Thanks for saying yes!");
} else {
alert("Too bad, you said no.");
}
}
function doBeep() {
beepCount = document.getElementById('beepSlider').value;
navigator.notification.beep(beepCount);
}
function doVibe() {
vibeCount = document.getElementById('vibeSlider').value;
navigator.notification.vibrate(vibeCount);
}
</script>
</head>
<body onload="onBodyLoad()">
<div data-role="header">
<h1>Notification Demo</h1>
</div>
<div data-role="content">
<div data-role="fieldcontain">
<label for="msgText">Message Text:</label>
<input type="text" name="msgText" id="msgText"
value="This is a message" />
<div data-role="controlgroup" data-type="horizontal">
<input type="button" value="Alert"
onclick="doAlert();">
<input type="button" value="Confirm"
onclick="doConfirm();">
</div>
</div>
<div data-role="fieldcontain">
<label for="beepSlider" >Number of Beeps</label>
<input type="range" name="beepSlider" id="beepSlider"
value="1" min="1" max="3" />
<input type="button" value="Beep" onclick="doBeep();">
</div>
<div data-role="fieldcontain">
<label for="vibeSlider" >Vibrate Duration</label>
<input type="range" name="vibeSlider" id="vibeSlider"
value="100" min="100" max="1000" step="100" />
<input type="button" value="Vibrate"
onclick="doVibe();">
</div>
</div>
</body>
</html>
The application makes use of HTML sliders to allow the user to more easily select beep counters or vibration duration. It also uses the capabilities provided by jQuery Mobile (www.jquerymobile.com) to make the application more visually appealing. All of those div containers you see in the code with the data-role and data-type attributes are instructions to jQuery Mobile. Figure 21-4 shows the application running on an Android smartphone.
Figure 21-4 Example 21-1 running on an Android device