This chapter is from the book
This chapter is from the book
This chapter is from the book
PhoneGap Initialization
Now let’s take the previous example application and add some PhoneGap-specific stuff to it. The HelloWorld2 application listed next has been updated to include code that recognizes when the PhoneGap application has completed initialization and displays an alert dialog letting you know PhoneGap is ready.
HelloWorld2 Application
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html;
charset=utf-8">
<meta name="viewport" id="viewport"
content="width=device-width, height=device-height,
initial-scale=1.0, maximum-scale=1.0,
user-scalable=no;" />
<script type="text/javascript" charset="utf-8"
src="phonegap.js"/script>
<script type="text/javascript" charset="utf-8">
function onBodyLoad() {
document.addEventListener("deviceready",onDeviceReady,
false);
}
function onDeviceReady() {
navigator.notification.alert("PhoneGap is ready!");
}
</script>
</head>
<body onload="onBodyLoad()">
<hl>HelloWorld2</h1>
<p>This is a sample PhoneGap application.</p>
</body>
</html>
On the iPhone simulator, the application will display the screen shown in Figure 2-2.
)
Figure 2-2 HelloWorld2 application running on an iOS simulator
Within the <Head> section of the web page are two new entries: meta tags that describe the content type for the application and viewport settings.
The content-type setting is a standard HTML setting and should look the same as it would for any other HTML 5 application.
The viewport settings tell the web browser rendering the content how much of the available screen real estate should be used for the application and how to scale the content on the screen. In this case, the HTML page is configured to use the maximum height and width of the screen (through the width=device-width and height=device-height attributes) and to scale the content at 100% and not allow the user to change that in any way (through the initial-scale=1.0, maximum-scale=1.0, and user-scalable=no attributes).
NOTE
The viewport and associated attributes are not required; if they’re omitted, the browser will revert to its default behavior, which may result in the application’s content not consuming the full screen area available to it or zooming beyond it. Because there’s not much content in the HelloWorld2 application, it could, for example, consume only the upper half of the screen on some devices.
You may find that on some platforms the settings have no effect. On the BlackBerry Torch simulator, the height and width attributes are respected; on the BlackBerry Storm simulator, the application doesn’t consume the entire height of the screen no matter how the attributes are set.
There’s also a new script tag in the code that loads the PhoneGap JavaScript library:
<script type="text/javascript"charset="utf-8" src="phonegap.js"></script>
This loads the PhoneGap API library and makes the PhoneGap APIs available to the program. In this example, and all of the examples throughout the rest of the book, I’ll load the PhoneGap JavaScript library using this standard snippet of code. In reality, the PhoneGap file being loaded by your application will include version information in the file name. As I wrote the chapter, PhoneGap 1.0 had just been released, so the code in reality looked like this when I wrote the application:
<script type="text/javascript"charset="utf-8" src="phonegap-1.0.0.js"></script>
As I wrote subsequent chapters, the PhoneGap team released three additional versions of the framework. Rather than have inconsistent PhoneGap JavaScript file names in the book, I chose to just show phonegap.js as illustrated in the first example. In reality, many of the example applications used throughout the book were actually built using PhoneGap Build, which requires only the simple phonegap.js reference (or no reference at all), which is then replaced with the appropriate JavaScript file version PhoneGap Build is currently using.
Beginning with PhoneGap 1.5, the project team changed the name for the open source project to Cordova and changed the JavaScript file (for most but not all of the supported platforms) from phonegap.js to cordova.js. So, even though you’re working with PhoneGap, the JavaScript file name no longer matches the commercial name for the project.
JavaScript code in a PhoneGap application does not have immediate access to the PhoneGap APIs after the web application has loaded. The native PhoneGap application container must complete its initialization process before it can respond to calls JavaScript made using the PhoneGap APIs. To accommodate this delay in API availability, a web developer building PhoneGap applications must instruct the container to notify the web application when the PhoneGap APIs are available. Any application processing that requires the use of the APIs should be executed by the application only after it has received its notification that the APIs are available.
In the HelloWorld2 application, this notification is accomplished through the addition of an onload event defined in the page’s body section, as shown here:
<body onload="onBodyLoad()">
Within the onBodyLoad function, the code registers an event listener that instructs the application to call the onDeviceReady function when the device is ready, when the PhoneGap application container has finished its initialization routines:
document.addEventListener("deviceready", onDeviceReady, false);
In this example application, the onDeviceReady function simply displays a PhoneGap alert dialog (which is different from a JavaScript alert dialog), letting the user know everything is OK:
navigator.notification.alert("PhoneGap is ready!")
In production applications, this function could update the user interface (UI) with content created through API calls or do whatever other processing is required by the application. You’ll see an example of this in the next sample application.