Create cross-platform apps with PhoneGap and jQuery Mobile

Jacob Orshalick shows how simple it is to develop a cross-platform app using PhoneGap and the jQuery Mobile framework.

One of the biggest challenges of developing mobile applications is trying to port the application to multiple platforms. This can lead to extensive development costs, and the need for multiple skillsets internally in order to maintain the application. This has led to the development of a number of technologies that provide a cross-platform solution.

Arguably, the most popular of these technologies is PhoneGap. The solution allows developers to create applications with a familiar tool set: HTML, CSS, and JavaScript.


 When PhoneGap is combined with a mobile web development framework, it's possible to develop cross-platform mobile applications quickly. One of the most popular frameworks is jQuery Mobile due to its simplicity and native look and feel.

I'll demonstrate how to develop a simple application that uses PhoneGap APIs with jQuery Mobile to search for a list of contacts by name and display them (Figure A). Then, I'll show how to deploy the application to your Android device with PhoneGap.  Follow along with the step-by-step tutorial, or download and import the project.

Figure A



1. Install PhoneGap. It's platform dependent, so I refer you to the PhoneGap documentation.

2. Execute the following lines in a terminal window to create the application in the current directory: 

$ phonegap create ContactsList
$ cd ContactsList
$ phonegap run android

3. PhoneGap provides a variety of plugins for accessing the native APIs of a device.  This example will make use of the PhoneGap Contacts Plugin. To add the Contacts Plugin, execute the following at the command line:


$ phonegap local plugin add

4. Enable the plugin within your PhoneGap application by adding this line to the app/res/xml/config.xml file:


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

5. You must provide permissions to contacts within the AndroidManifest.xml, so within the application, add these lines to the app/AndroidManifest.xml file:


<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

6. Now you're ready to start developing the application. The first step is to create a page that will hold the list of contacts you're attempting to show. With jQuery Mobile, this is achieved using the <div data-role="page"> element. Copy this code snippet into the www/index.html file of your application:


<!DOCTYPE html> 
	<title>Page Title</title> 
	<meta name="viewport" content="width=device-width, initial-scale=1"> 

  <link rel="stylesheet" 
    href="" />
  <script type="text/javascript" src="phonegap.js"></script>
  <script src=""></script>
  <script type="text/javascript" src="js/index.js"></script>
  <div data-role="page">
    <div data-role="header">
      <h1>Show My Contacts</h1>
    </div><!-- /header -->

    <div data-role="content">	
      <div id="contactsList">
    </div><!-- /content -->
  </div><!-- /page -->

We included the jQuery Mobile script and stylesheet in the <head>; this is all that is needed to use the jQuery Mobile framework. Within the <div data-role="page"> element, we define the <div data-role="header"> and <div data-role="content"> elements. These elements define what content will be rendered in the page header and the content section, respectively.

7. In the previous snippet, there was an empty <div id="contactsList">; this <div> element will contain your contacts list. You can use JavaScript to retrieve the contacts and display them. PhoneGap provides an event to hook into the moment the application is loaded, and the device is ready. Replace the code in the www/js/index.js file with the following:


document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
    // find all contacts with 'Jacob' in any name field
    var options = new ContactFindOptions();
    options.filter = "Jacob";
    options.multiple = true; 
    var fields = ["displayName", "name", "phoneNumbers"];
    navigator.contacts.find(fields, onSuccess, onError, options);
This code snippet adds a listener that will retrieve all contacts with "Jacob" anywhere in the name once the device is ready. The data returned from the retrieval will contain the contact names and phone numbers, and will be passed to an onSuccess method.

8. After retrieving the contacts, you need to display them to the user. You can use the jQuery Mobile Collapsible List to display the contact names and allow them to be expanded to show the phone numbers. Add the following snippet to the www/js/index.js file:


function onSuccess(contacts) {
  for(var i = 0; i < contacts.length; i++) {
    var html = '<div data-role="collapsible" data-inset="false">';

    html += '<h2>' + contacts[i].displayName + '</h2>';
    html += '<ul data-role="listview">'

    var contact = contacts[i];

    for(var j = 0; j < contact.phoneNumbers.length; j++) {
      html += '<li>' + contact.phoneNumbers[j].type + 
        ": " + contact.phoneNumbers[j].value + '</li>';

    html += '</ul></div>';



function onError(contactError) {
Notice that we make use of the PhoneGap Contact object here. Be sure to specify the fields you want to use when finding the contacts list.

9. If you have your Android device or an emulator set up appropriately, execute this command to deploy the application:


$ phonegap install android

Keep exploring

Try deploying the application to other platforms and using additional PhoneGap APIs. It may just convince you to use the platform for your next app.


By Jacob Orshalick

Jacob Orshalick is a software consultant, open source developer, speaker, and author. He is the owner of solutionsfit and co-author of the best-selling Seam Framework: Experience the Evolution of Java EE. His software development experience spans the...