Table of Contents for

The Modern Web

Once your setup is complete, you can add all the files to the project that your app needs to run, and then begin to take advantage of the PhoneGap API. Some of the properties in the API require that you add permission requests to a manifest file because (as I mentioned earlier) PhoneGap uses the XML-based widgets specification for requests. For example, to request access to the Notification API, you include the following XML element in the file config.xml:

<plugin name="Notification" value="org.apache.cordova.Notification"/>

Some platforms require no extra permissions, or make some methods available without requiring permissions, whereas others insist on permission requests for all methods. The API documentation has full details.

The PhoneGap API is largely composed of a series of properties and methods on the navigator object. Some of these properties are already available through browsers. When they are, as with the geolocation object you learned about in Chapter 6, PhoneGap’s API chooses the native implementation first, falling back to its own implementation on systems where the property is not available.

Other properties require heightened permissions and, as such, are available on some platforms exclusively through PhoneGap. For example, consider the contacts object, which provides access to the user’s contact list—not something you want exposed to the Web without special authorization.

The contacts object has two functions: create() and find(). To select items from the contacts list, you use the latter with two required arguments: contactFields (a list of fields to return) and contactSuccess (a function to be run when a successful query takes place).

In the following code, I set up a query to get the display name and birthday of all contacts in the address book; then if this query is successful, it runs an anonymous function. This function loops through all of the results (in the contacts object I defined) and adds them to a string called contactDOB, which I use here to populate a list.

navigator.contacts.find(['displayName','birthday'], function (results) {
  var i, contactDOB;
  for (i=0; i < results.length; i++) {
    contactDOB += '<li>' + results[i].displayName + '(' + results[i].
birthday + ')</li>';
  }
});

Future browsers and web-based operating systems (such as Firefox OS) will probably provide direct access to some of these methods in the future, meaning the long-term future of PhoneGap will likely be in polyfilling features on legacy devices. PhoneGap’s developers are cognizant of this, as stated clearly in a blog post called “Beliefs, Goals and Philosophy”:

In addition to its device properties API, PhoneGap also has a number of extremely useful events that register changes to the device’s status, from its network status and capability to the battery level. These events are critical if you want your app to provide users with the best possible experience, such as ensuring data is saved before a battery runs out or when network connection is lost.

The most important event is deviceready, which fires when PhoneGap has fully loaded and is ready to execute. The deviceready event is functionally identical to the DOMContentLoaded event you saw in Chapter 5 in that it also should be used in every script to ensure that all required libraries have been loaded and are in place before the rest of the scripts are run. As such, all of your functions that require access to the PhoneGap API should be run in the callback function:

document.addEventListener('deviceready', function () {
  // All PhoneGap-related functions
}, false);

Other events include pause and resume. The former is fired when the current application is closed and moved to a background process, and the latter when it becomes active again. For example, you may want to store data when the application is moved to a background process to make sure users doesn’t lose their work:

document.addEventListener('pause', function () {
  // Backup data
}, false);

Some events fire when an application disconnects or reconnects from a network (offline and online); when the volume or call buttons are pressed (volumedownbutton, volumeupbutton, startcallbutton, and endcallbutton); and when the battery status changes (batterystatus detects changes in status, whereas batterylow and batterycritical fire when the battery is low or in a critical state, as defined by the device).