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
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.
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.
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");
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.");
}
}
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.
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.
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.