Cordova exposes a number of methods a web application can call to allow the application to interact with the user. Web developers have always had access to the synchronous JavaScript alert(),
confirm(), and prompt() methods, which can be used to interact with the user, but the Cordova versions of these functions are asynchronous and allow for additional control over the content in the dialog that is displayed to users.
To leverage visual notifications in your Cordova applications, you must first add the dialogs plugin to your project by opening a terminal window and issuing the following CLI command from the Cordova project folder:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git
A Alleerrtt
To display an alert dialog in a web application, a web developer can have an application execute the following JavaScript code:
alert("This is a JavaScript alert.");
When the code runs in a Cordova application, you will see something similar to Figure 12. 4.
FFiigguurree 1122..44 JavaScript alert Results
If you instead use the Cordova alert() method by executing the following code:
navigator.notification.alert("This is a Cordova Alert.", myCallback, "Alert Test", "Click Me!")
ptg11524036 you will see a dialog similar to the one shown in Figure 12.5.
FFiigguurree 1122..55 Cordova alert Results
Notice that I was able to set the title for the dialog (instead of the Cordova application reporting index.html, as shown in Figure 12.4) as well as the text on the button the user taps to close the alert. I mentioned that the JavaScript alert was synchronous and the Cordova alert was asynchronous; this means that the JavaScript alert will likely display immediately, but the Cordova alert will display whenever the Cordova container gets around to rendering it. This is an oversimplification of what’s going on, but you can read more about it in an article I wrote here:
www.johnwargo.com/index.php/mobile-development/phonegap-alerts.html.
Now, in that example, I didn’t tell you a lot about the format of the call to alert; in the following example, you can see the descriptive names of the parameters:
navigator.notification.alert(message, callback, [title], [buttonLabel])
Notice the callback parameter; it’s there to allow you to define the function that is executed when the user taps the button on the alert dialog. The way you use the Cordova alert is to execute the alert
method, then use the callback function to continue program execution after the user taps the button. What happens is that any code you have after the call to alert is executed, perhaps finishing out the code in a JavaScript function, and the application will sit idle until the user taps the button; then the code in the callback function executes.
In the earlier example, I passed in a null value for the callback parameter. In this scenario, by not telling alert what function to call after the user taps the button, the Cordova container will render the specified alert dialog, then continue executing the JavaScript code that follows the call to alert and not wait for the user to tap the button.
The values for title and buttonLabel are optional; the value for title passed to the method will be used as the title for the dialog, and the buttonLabel value will be used as the text on the single button on the dialog.
C
Coonnffiirrmm
The Cordova confirm method is similar to alert except that it allows you to specify more than one button label, and the callback function is passed a numeric value indicating which button was tapped by the application user. Here’s the method signature:
navigator.notification.confirm(message, callback, [title], [buttonLabels]);
ptg11524036
navigator.notification.confirm('Do you want to continue?', doContinue, 'Please confirm', 'Yes, No');
function doContinue(buttonNum){
navigator.notification.alert('You chose option #' + buttonNum + '?', null, 'Really?','Yes');
};
The value passed to the callback function is a numeric value indicating which button was tapped. The callback function will receive a 1 if the first button was clicked, a 2 for the second button, and so on. Figure 12.6 shows confirm in action on iOS.
FFiigguurree 1122..66 Cordova confirm Dialog
Figure 12.7 shows the results of the doContinue function being executed, indicating that the No button was tapped in Figure 12.6.
FFiigguurree 1122..77 Showing confirm Results
PPrroommpptt
A Cordova application often needs to collect information from the application user outside of a web form; Cordova provides the prompt method to accommodate this requirement. The method works just like the other methods discussed in this section and has the following method signature:
navigator.notification.prompt(message, callback, [title], [buttonLabels], [defaultText]);
The parameters in brackets are optional. To use prompt in your Cordova applications, make a call to the prompt method and provide the necessary callback function to process the user’s input:
ptg11524036
gotData, 'Nickname?', ['Cancel', 'OK'], 'Jimmy'); function gotData(res) {
navigator.notification.alert('You chose option #' + res.buttonIndex + '\nYou entered: ' + res.input1, null, 'Results', 'OK');
};
N Noottee
Notice that prompt uses a different format for button labels than confirm uses. prompt expects an array of strings, as shown in the previous example, and confirm expects a single string with the button labels separated by a comma.
Figure 12.8 shows the example code in action on an Android emulator.
FFiigguurree 1122..88 Cordova prompt Dialog
Figure 12.9 shows the results displayed by gotData function.
ptg11524036