Notification
Visual, audible, and tactile device notifications.
Methods
notification.alert
Shows a custom alert or dialog box.
navigator.notification.alert(message, alertCallback, [title], [buttonName])
-
message: Dialog message (
String) -
alertCallback: Callback to invoke when alert dialog is dismissed. (
Function) -
title: Dialog title (
String) (Optional, Default: "Alert") -
buttonName: Button name (
String) (Optional, Default: "OK")
Description
Most PhoneGap implementations use a native dialog box for this feature. However, some platforms simply use the browser's alert function, which is typically less customizable.
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 and higher)
- iPhone
- Windows Phone 7 ( Mango )
Quick Example
// Android / BlackBerry WebWorks (OS 5.0 and higher) / iPhone
//
function alertDismissed() {
// do something
}
navigator.notification.alert(
'You are the winner!', // message
alertDismissed, // callback
'Game Over', // title
'Done' // buttonName
);
// BlackBerry (OS 4.6) / webOS
//
navigator.notification.alert('You are the winner!');
Full Example
<!DOCTYPE html>
<html>
<head>
<title>Notification Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap is ready
//
function onDeviceReady() {
// Empty
}
// alert dialog dismissed
function alertDismissed() {
// do something
}
// Show a custom alert
//
function showAlert() {
navigator.notification.alert(
'You are the winner!', // message
alertDismissed, // callback
'Game Over', // title
'Done' // buttonName
);
}
</script>
</head>
<body>
<p><a href="#" onclick="showAlert(); return false;">Show Alert</a></p>
</body>
</html>
Windows Phone 7 Quirks
- Ignores button names, always uses 'OK'
notification.confirm
Shows a customizable confirmation dialog box.
navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
-
message: Dialog message (
String) -
confirmCallback: - Callback to invoke with index of button pressed (1, 2 or 3). (
Number) -
title: Dialog title (
String) (Optional, Default: "Confirm") -
buttonLabels: Comma separated string with button labels (
String) (Optional, Default: "OK,Cancel")
Description
Function notification.confirm displays a native dialog box that is more customizable than the browser's confirm function.
Supported Platforms
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iPhone
- Windows Phone 7 ( Mango )
Quick Example
// process the confirmation dialog result
function onConfirm(button) {
alert('You selected button ' + button);
}
// Show a custom confirmation dialog
//
function showConfirm() {
navigator.notification.confirm(
'You are the winner!', // message
onConfirm, // callback to invoke with index of button pressed
'Game Over', // title
'Restart,Exit' // buttonLabels
);
}
Full Example
<!DOCTYPE html>
<html>
<head>
<title>Notification Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap is ready
//
function onDeviceReady() {
// Empty
}
// process the confirmation dialog result
function onConfirm(button) {
alert('You selected button ' + button);
}
// Show a custom confirmation dialog
//
function showConfirm() {
navigator.notification.confirm(
'You are the winner!', // message
onConfirm, // callback to invoke with index of button pressed
'Game Over', // title
'Restart,Exit' // buttonLabels
);
}
</script>
</head>
<body>
<p><a href="#" onclick="showConfirm(); return false;">Show Confirm</a></p>
</body>
</html>
Windows Phone 7 Quirks
- Ignores button names, always 'OK|Cancel'
notification.beep
The device will play a beep sound.
navigator.notification.beep(times);
-
times: The number of times to repeat the beep (
Number)
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 and higher)
- iPhone
- Windows Phone 7 ( Mango )
Quick Example
// Beep twice!
navigator.notification.beep(2);
Full Example
<!DOCTYPE html>
<html>
<head>
<title>Notification Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap is ready
//
function onDeviceReady() {
// Empty
}
// Show a custom alert
//
function showAlert() {
navigator.notification.alert(
'You are the winner!', // message
'Game Over', // title
'Done' // buttonName
);
}
// Beep three times
//
function playBeep() {
navigator.notification.beep(3);
}
// Vibrate for 2 seconds
//
function vibrate() {
navigator.notification.vibrate(2000);
}
</script>
</head>
<body>
<p><a href="#" onclick="showAlert(); return false;">Show Alert</a></p>
<p><a href="#" onclick="playBeep(); return false;">Play Beep</a></p>
<p><a href="#" onclick="vibrate(); return false;">Vibrate</a></p>
</body>
</html>
Android Quirks
- Android plays the default "Notification ringtone" specified under the "Settings/Sound & Display" panel.
iPhone Quirks
- Ignores the beep count argument.
- There is no native beep API for iPhone.
- PhoneGap implements beep by playing an audio file via the media API.
- The user must provide a file with the desired beep tone.
- This file must be less than 30 seconds long, located in the www/ root, and must be named
beep.wav.
Windows Phone 7 Quirks
- WP7 PhoneGap lib includes a generic beep file that is used.
notification.vibrate
Vibrates the device for the specified amount of time.
navigator.notification.vibrate(milliseconds)
-
time: Milliseconds to vibrate the device. 1000 milliseconds equals 1 second (
Number)
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 and higher)
- iPhone
- Windows Phone 7
Quick Example
// Vibrate for 2.5 seconds
//
navigator.notification.vibrate(2500);
Full Example
<!DOCTYPE html>
<html>
<head>
<title>Notification Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap is ready
//
function onDeviceReady() {
// Empty
}
// Show a custom alert
//
function showAlert() {
navigator.notification.alert(
'You are the winner!', // message
'Game Over', // title
'Done' // buttonName
);
}
// Beep three times
//
function playBeep() {
navigator.notification.beep(3);
}
// Vibrate for 2 seconds
//
function vibrate() {
navigator.notification.vibrate(2000);
}
</script>
</head>
<body>
<p><a href="#" onclick="showAlert(); return false;">Show Alert</a></p>
<p><a href="#" onclick="playBeep(); return false;">Play Beep</a></p>
<p><a href="#" onclick="vibrate(); return false;">Vibrate</a></p>
</body>
</html>
iPhone Quirks
-
time: Ignores the time and vibrates for a pre-set amount of time.
navigator.notification.vibrate(); navigator.notification.vibrate(2500); // 2500 is ignored