PhoneGap and Dojo Mobile on Android


Content series:

This content is part # of # in the series: Mobile application development, Part 1

Stay tuned for additional content in this series.

This content is part of the series:Mobile application development, Part 1

Stay tuned for additional content in this series.

Everywhere you go, people are using mobile devices to keep in touch with family and friends, take a picture to post on a social website, find the location of a restaurant, or check the latest news headlines. Mobile devices come in many different shapes and styles. Mobile phones run a variety of different operating systems such as Apple's iOS, Google's Android, and Research In Motion's Blackberry. Some have large displays, physical keyboards, and run on 3G, 4G, or WiFi networks. Mobile phones may also have sensors for acceleration, location, or even payments. Some of these devices aren't even phones; they're tablets with larger displays and a data-only network connection.

Despite their differences, mobile devices are similar in that they all run mobile applications. Mobile applications can be divided into two types:

Native applications

Installed on the device, native applications are binary executable programs created using a software development kit (SDK) and distributed through an app store. There is an SDK for each mobile operating system, which unfortunately is different from the SDKs of other operating systems.

For example, to create an application for iOS, you must download and install the iOS SDK and development tools, and you must code your application using the Objective-C programming language. An Android application is developed using the Android SDK and written in Java. Thus, to create a mobile application, you must learn each SDK and write your application using the supported programming language. There's a steep learning curve for each platform's SDK, so mobile application development is quite complex.

Web applications

Loaded into the mobile web browser, web applications are different from native applications in that they're coded using web technologies (HTML, JavaScript, and CSS) regardless of the device's operating system. There's no need to learn different programming languages for each device. HTML and JavaScript are familiar to web developers since they're used to create web pages loaded into your desktop browser. For the most part, mobile browsers can render the same web page, but websites often provide a mobile version that has less content and loads faster (due to a smaller screen size and slower network connection).

To "run" a web application, the user enters a URL into the mobile web browser. This loads the web page, which is the entry point into a web application. Web applications are not distributed through an app store; they are simply links that can be included in other web pages, e-mails, or even hard copy.

Native and web applications both have advantages and disadvantages, and many arguments have been waged over which is better. In an effort to resolve this battle, a new hybrid application tries to combine the advantages from both native and web applications.

Hybrid applications are programmed using web technologies, like web applications, but are packaged as a native application. A hybrid application can be written once for multiple device operating systems using a programming language familiar to many developers. Since a hybrid application is really a native application, you have access to device features from JavaScript that are not currently available to web applications. Hybrid applications can also be distributed and installed using app stores, just like a native application.

PhoneGap is a popular toolkit for building hybrid applications. It's an open source mobile framework that includes a JavaScript API for access to device features, such as the accelerometer and camera.

This article shows you how to develop a hybrid mobile Android application using the PhoneGap and Dojo Mobile toolkits. Learn how to use the Android emulator and tools for testing applications, and see how to run your application on an Android device or tablet.


This article assumes you have some familiarity with the Eclipse development environment, HTML, JavaScript, and CSS. The following software is required:

  • Windows, OSX, or Linux operating system
  • Java Development Kit (JDK) 5 or JDK 6 (a JRE is not sufficient)
  • An Eclipse development environment, such as Eclipse Helios V3.6 or later, or IBM Rational Application Developer V8
  • Android SDK and platforms (r12 or later)
  • Android Development Toolkit (ADT) plugin for Eclipse
  • PhoneGap SDK (V1.0.0 or later)
  • Dojo Toolkit (V1.6 or later)

See Related topics for links to download the software.

Set up your development environment

To set up the development environment, you need to perform the following steps:

  1. Install the JDK and Eclipse or Rational Application Developer.
  2. Download the Android SDK.
  3. Download and install the ADT plugin for Eclipse.
  4. Configure Eclipse for Android.
  5. Install the required Android platforms.
  6. Create a new Android Virtual Device (AVD).
  7. Download the PhoneGap SDK.
  8. Download the Dojo Toolkit.

Install the JDK and Eclipse or Rational Application Developer

The first task is to verify that JDK 5 or greater is installed. If not, download Java SE JDK (see Related topics).

You can use either Eclipse or IBM Rational Application Developer (RAD) for this article. Windows or Linux is supported by RAD. OSX developers can use Eclipse.

RAD consists of IBM's version of Eclipse with additional IBM tools to support Java EE, including IBM's Web 2.0 Feature Pack. To use RAD, you will need Version 8 or later. RAD includes IBM's JDK, which is used by default. However, this JDK does not contain the Java packages needed to create and sign an Android application. To use the Java SE JDK instead, you need to replace C:/Program Files/IBM/SDP/eclipse.ini (or the location you installed RAD) with the information in Listing 1.

Listing 1. Content of eclipse.ini for RAD on Windows
C:/Program Files/IBM/SDP

If you want to use Eclipse, you will need Version 3.6 or later. Since you'll be writing web services later in this series, download the Eclipse IDE for Java EE Developers (see Related topics). However, if you only want to write an Android application, you can get by with using the Eclipse IDE for Java Developers.

Eclipse and RAD are very similar. In this article, when Eclipse is mentioned it implies either Eclipse or RAD. However, figures of screens are from RAD running on Windows.

Download the Android SDK

The Android SDK (see Related topics) must be used to make Android applications. It is a collection of command line programs that are used to compile, build, emulate, and debug Android applications.

If you are installing on Windows, it's easiest to download the zip package and extract it into your C:\ root directory. There are a couple of issues with the r12 installer not being able to detect Java or install into a directory with spaces in it's name.

Download and install the ADT plugin

Android provides an Eclipse plugin that greatly simplifies application development. It integrates with Eclipse to provide a rapid development environment. To install the Android Development Toolkit (ADT) plugin (see Related topics), follow the steps below:

  1. From Eclipse, select the menu items Help > Install New Software… > Add…
  2. Enter the name and URL location of the software, as shown in Figure 1. Name: Android ADT Eclipse plugin; location:
    Figure 1. Installing Android ADT plugin
    Installing Android ADT plugin
    Installing Android ADT plugin
  3. Select Developer Tools, verify that all check boxes are selected, as shown in Figure 1, and then select Next.
  4. As shown in Figure 2, select Next to accept license agreements and install the items.
    Figure 2. Install details
    Install details
    Install details

After installation is complete, restart Eclipse.

Configure Eclipse for Android

To configure Eclipse for Android, display the Preferences dialog.

  • For Windows, select Window > Preferences > Android.
  • For OSX, select Eclipse > Preferences > Android.

For the SDK location, select Browse…, and then choose the directory where the Android SDK is located, as shown in Figure 3:

Figure 3. Specify SDK location to Eclipse
Specify SDK location to Eclipse
Specify SDK location to Eclipse

Select Apply and OK.

Add the Android LogCat view to the Eclipse IDE to aid with debugging:

  • Window > Show View > Other…
  • Android > LogCat
Figure 4. LogCat view
LogCat view
LogCat view

Install an Android platform

To compile an Android application for a particular version, one or more Android platforms must be downloaded and installed. The platforms include the library files and emulators.

From Eclipse, open the Android SDK and AVD Manager, which is used to manage the Android SDK versions and emulators used with your applications.

Select Window > Android SDK and AVD Manager, as shown in Figure 5:

Figure 5. Menu item for Android configuration
Menu item for Android configuration

Install the SDK platforms required for the versions of Android on which you wish to run your applications.

The example application will be using GPS location services, so you should select and install a platform based upon the Google APIs. For example, select Google APIs by Google Inc., Android API 8, revision 2, as shown in Figure 6. If you are not using GPS, then you can install platforms listed under the Android Repository category.

For Windows installations, select the Google USB Driver package to provide support for connecting your Android phone.

Select Install Selected.

Figure 6. Android SDK and AVD Manager
Android SDK and AVD Manager
Android SDK and AVD Manager

Accept the licence agreement for each package, and then select Install, as shown in Figure 7:

Figure 7. Android packages to install
Android packages to install
Android packages to install

The manager will download and install the selected packages.

Create a virtual Android device

The Android SDK and AVD Manager are also used to create and manage the emulator instances to be used with your applications.

From the Virtual Devices page, select New… to create a new AVD. As shown in Figure 8, enter a name, target, SD card size, and HVGA skin:

Figure 8. Creating a new AVD
Screenshot of 'Create new AVD' window with 'AVD1' entered as name, 'Google APIs (Google, Inc.) - API Level 8' entered as target, 20 MB selected for SD card size, and built-in HVGA selected for skin
Screenshot of 'Create new AVD' window with 'AVD1' entered as name, 'Google APIs (Google, Inc.) - API Level 8' entered as target, 20 MB selected for SD card size, and built-in HVGA selected for skin

Select Create AVD.

Download PhoneGap SDK

PhoneGap is an open source hybrid mobile application framework that supports multiple platforms, including Android, iOS, Blackberry, Palm, Symbian, and Windows Phone. With PhoneGap you can easily write a cross-platform mobile application using standard web technologies (HTML, JavaScript, and CSS) and access device features such as the accelerometer or camera from JavaScript. See Related topics for a link to information for the supported features, which provides the latest details about PhoneGap.

PhoneGap provides a collection of JavaScript APIs that enables access to many device features not available from the mobile web browser for a typical web application. This is accomplished by using a native wrapper around your web application. PhoneGap combines web application code with the device's browser renderer to produce a native application that can be deployed to an app store and installed on the device.

Features included as part of the PhoneGap API enable access to a device's accelerometer, audio and video capture, camera, compass, contacts, file, geolocation, network, notification, and storage. The PhoneGap API documentation (see Related topics) has more details and examples.

After you download PhoneGap (see Related topics), you'll later copy the code into your Android project (in the "Create a new Android project" section).

Download Dojo

Dojo Toolkit is an open source JavaScript toolkit designed for rapid development of websites and applications that are loaded and run in a web browser.

Since mobile web browsers are not as capable as desktop browsers, Dojo includes a mobile version, called Dojo Mobile. It is optimized for mobile web browsers, and it provides many UI widgets and themes you can use to style your mobile application to mimic a native application.

Some key features of Dojo Mobile include:

  • Lightweight loading of widgets due to the Dojo Mobile parser
  • CSS3 animations and transitions for native-like application experience on high-end iOS and Android devices
  • Themes included for both iOS and Android look and feel
  • Compatibility with non-CSS3-compatible devices and browsers
  • Full declarative syntax, allowing for an easy learning curve
  • A large suite of widgets, with even more in the upcoming Dojo Mobile 1.7

For this article, you will need to download Dojo 1.6 (see Related topics).

Create a new Android project

Now that the development environment is set up, let's start by creating a simple Android application.

From Eclipse, select File > New > Other…, then Android > Android project. You should see the dialog shown in Figure 9.

Figure 9. New Android project
Screenshot of 'New Android project' window with 'AndroidPhoneGap' entered as project name, Google APIs selected as build target, 'Android PhoneGap' entered as application name, '' entered as package name, and 'App' entered as activity name
Screenshot of 'New Android project' window with 'AndroidPhoneGap' entered as project name, Google APIs selected as build target, 'Android PhoneGap' entered as application name, '' entered as package name, and 'App' entered as activity name

As shown in Figure 9, enter a project name, select a build target, and enter the application name, package name, and activity name. Click on Finish to create the project.

Add the PhoneGap library

You now have a simple Android application. Before you can write a PhoneGap application, you need to add the PhoneGap library. There are two files: a JavaScript file that contains the PhoneGap API called by our application, and a native JAR file containing the native implementation for the PhoneGap API.

  1. Expand the AndroidPhoneGap project tree view, as shown in Figure 10:
    Figure 10. Android project with PhoneGap library
    Android project with PhoneGap library
  2. Create the directory \assets\www. Also create the directory \libs if it doesn't already exist.
  3. Unzip the PhoneGap download and locate the Android subdirectory.
  4. Copy the three PhoneGap library files for Android to the following Eclipse project folders:
    • Copy phonegap-1.0.0.jar to \libs\phonegap-1.0.0.jar
    • Copy phonegap-1.0.0.js to \assets\www\phonegap-1.0.0.js
    • Copy xml/plugins.xml to \res\xml\plugins.xml

Even though the PhoneGap JAR file is copied into the project, you also need to add it to the project's build path.

  1. Select Project > Properties > Java Build Path > Libraries > Add JARs….
  2. Add phonegap-1.0.0.jar by navigating to it in the project, as shown in Figure 11:
Figure 11. Adding PhoneGap JAR
Adding PhoneGap JAR
Adding PhoneGap JAR

The final step in preparing the example Android application to use PhoneGap is to modify Because a PhoneGap application is written in HTML and JavaScript, you need to change to load your HTML file using loadUrl(), as shown in Listing 2. You can edit by double-clicking on in the tree view shown in Figure 10.

Listing 2.
import android.os.Bundle;
import com.phonegap.*;
public class App extends DroidGap //Activity
    /** Called when the activity is first created. */
    public void onCreate(Bundle savedInstanceState)

Write the PhoneGap application

You're now ready to start writing the PhoneGap application. For Android, files under the asset directory are referenced using file:///android_asset. As specified in loadUrl() in Listing 2, you need to create an index.html file under assets/www.

After creating index.hml, enter the contents of Listing 3 below.

Listing 3. index.html
<script type="text/javascript" charset="utf-8" src="phonegap-1.0.0.js"></script>
<body onload='document.addEventListener("deviceready", deviceInfo, false);'>
function deviceInfo() {
    document.write("<h1>This is Phonegap 1.0.0 running on "+device.platform+" 

A brief explanation of index.html is in order. Before calling any PhoneGap APIs, we must wait for the deviceready event, which indicates that the native portion of PhoneGap has been initialized and is ready. In Listing 3, the onload callback registers for deviceready. When it fires, we write out the device's OS and version.

Since PhoneGap uses native features that are protected by permissions, you need to modify AndroidManifest.xml to include these uses-permission tags. You also need to specify the support-screens tag, the android:configChanges property, and the com.phonegap.DroidGap activity tag, as shown in Listing 4:

Listing 4. AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android=""
 <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application android:icon="@drawable/icon" android:label="@string/app_name">
   <activity android:name=".App"
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   <activity android:name="com.phonegap.DroidGap" android:label="@string/app_name" 

Run the application in the Android emulator

The PhoneGap application is now ready to run. Select Run > Run As > Android Application, and you should see something similar to Figure 12

Figure 12. Android emulator
Screenshot of Android emulator and message 'This is PhoneGap 1.0.0 running on Android 2.2!'
Screenshot of Android emulator and message 'This is PhoneGap 1.0.0 running on Android 2.2!'

Eclipse automatically builds the application, launches the emulator, and installs and runs it on the emulator.

The emulator can take several minutes to start up. To speed development, keep the emulator running until you are done with your development session. Eclipse will automatically use a running emulator instead of launching a new one.

Run the application on an Android phone

If you have an Android phone, you can run the PhoneGap application on your device. However, before you can use your phone for development, you need to turn on USB debugging, as follows:

  1. Go to the Home screen and select Menu.
  2. Select Settings > Applications > Development.
  3. Enable USB debugging.
  4. You also need to declare the application as debuggable in the Android Manifest. Edit the AndroidManifest.xml file to add android:debuggable="true" to the <application> element.
  5. Attach an Android phone to your development machine with USB.
  6. To run the application, select Run As > Android Application.

    You will be prompted to choose between the emulator or real device as the target. Select the Android phone, as shown in Figure 13:

    Figure 13. Select the device
    Select the device
    Select the device

Once the application has been downloaded and installed on your phone, it will be launched, as shown in Figure 14:

Figure 14. Application running on device
Application running on device
Application running on device

Use the Dalvik Debug Monitor Server (DDMS)

The ADT plugin includes a Dalvik Debug Monitor Server (DDMS) perspective for debugging. DDMS, which can be used to track and debug the application flow, can be used with the emulator or a real device.

The DDMS perspective can be started from Eclipse by selecting Window > Open Perspective > Other... > DDMS. Figure 15 shows an example.

Figure 15. DDMS window inside Eclipse
DDMS window inside Eclipse
DDMS window inside Eclipse

The DDMS can also be started using command line from the location of the Android SDK.

  • For Windows: C:\android-sdk-windows\tools\ddms.bat
  • For OSX: .../android-sdk-mac-86/tools/ddms
Figure 16. Standalone debugger
Standalone debugger
Standalone debugger

From DDMS, you can:

  • View the log console
  • Show the status of processes on the device
  • Examine thread information
  • View heap usage of a process
  • Force garbage collection
  • Track memory allocation of objects
  • Perform method profiling
  • Work with a device's file system
  • Perform screen captures of the device
  • Emulate phone operations

See the DDMS documentation (in Resource) for more information.

Extend the project with Dojo

Dojo is a JavaScript toolkit that offers several benefits to mobile applications. It provides themes that mimic native mobile applications, and it has user interface (UI) containers and widgets that simplify development of your application UI.

Setup for Dojo

To use Dojo, you need to copy it into the example project.

Create the following directories, as shown in Figure 17.

  • \assets\www\libs
  • \assets\www\libs\dojo
  • \assets\www\libs\dojo\dojo
  • \assets\www\libs\dojo\dojox

Copy the following Dojo files:

  • dojox\mobile.js to \assets\www\libs\dojo\dojox directory
  • dojox\mobile directory to \assets\www\libs\dojo\dojox directory
  • dojo\dojo.js to \assets\www\libs\dojo\dojo directory
Figure 17. Android project tree with Dojo added
Android project tree with Dojo added

To load Dojo, you need to edit index.html and include the lines in Listing 5 in the <head> section before the phonegap-1.0.0.js script tag.

Listing 5. Adding Dojo to index.html
<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,
<link rel="stylesheet" href="libs/dojo/dojox/mobile/themes/android/android.css" 
type="text/css" media="screen" title="no title" charset="utf-8">
<script type="text/javascript" src="libs/dojo/dojo/dojo.js" djConfig="parseOnLoad:true">

After the phonegap-1.0.0.js script tag, include the require statements, as shown in Listing 6, for the Dojo mobile parser.

Listing 6. Modify index.html to load mobile Dojo
<script type="text/javascript">

Updating the application

Replace the existing <body> tag in index.html with a new <body> tag that contains two simple <div> sections, as shown in Listing 7:

Listing 7. Modify body of index.html
<div dojoType="" id="accHelp" selected="true">
    <h1 dojoType="">Accident</h1>
    <div class="text">If you are in an accident, you should first move to a safe 
    location. Below are some additional actions you can take:</div>
    <ul dojoType="">
        <li dojoType="" 
            onclick="window.location='geo:0,0?q=police';">Call the Police</li>
        <li dojoType=""
            onclick="window.location='geo:0,0?q=towing';">Call for a Tow Truck</li>
        <li dojoType="" moveTo="accInfo" transition="slide"
            onClick="itemClicked();">Exchange Driver Info</li>
        <li dojoType="" moveTo="accInfo" transition="slide"
            onClick="itemClicked();">Record Accident Location</li>
        <li dojoType="" moveTo="accInfo" transition="slide"
            onClick="itemClicked();">Take Photos of Accident</li>
<div dojoType="" id="accInfo">
    <h1 dojoType="" back="Accident" moveTo="accHelp"
        onClick="console.log('Going back');">Driver</h1>
    <h2 dojoType="">Other Driver Info</h2>

As shown in Listing 8, add a simple JavaScript function, itemClicked() after the last <div> tag to log to the console.

Listing 8. Onclick handler
function itemClicked() {

Running on an emulator

Run the application as an Android application by right-clicking on the project and selecting Run as > Android Application.

Figure 18. Application running on emulator
Application running on emulator
Application running on emulator

Each screen in a Dojo application is defined by a div element with dojoType='', as shown in Listing 9. The initial screen is identified with the attribute selected='true'.

The title of the screen is defined by a <h1 dojoType=''> tag.

Listing 9. Defining screen and title
<div dojoType="" id="accHelp" selected="true">
    <h1 dojoType="">Accident</h1>

Notice the > on the last three list items. It is an indicator that another Dojo screen will be loaded.

A list item tag with dojoType='' is used to display a list of items that can be selected, as shown in Listing 10. It is rendered as a native selection list. The moveTo attribute specifies which div to display, and the transition attribute specifies how it is to be moved into view.

Listing 10. List item to load a new screen
<li dojoType="" moveTo="accInfo" transition="slide"
    onClick="itemClicked();">Exchange Driver Info</li>

Select Exchange Driver Info, which will hide the current div and show the target div with id='accInfo'. You should see the Driver screen slide into view, as shown in Figure 19

Figure 19. Driver information screen
Driver information screen
Driver information screen

The list items can be used for more than loading other screens. For example, the onclick handler can be used to display a Google map with a search for the nearest police station. Listing 11 shows the code.

To return back to the previous screen, select the Accident button in the title.

Listing 11. List item to load a Google map
<li dojoType="" 
    onclick="window.location='geo:0,0?q=police';">Call the Police</li>

Many mobile devices support the geo: protocol. By loading a URI of the form geo:lat,lng?q=query, the native Google map service will be displayed.

Select Call the Police on the emulator, which will display a map of the nearest police station, as shown in Figure 20:

Figure 20. Search for nearest police station
Search for nearest police station
Search for nearest police station

Your location may be different, depending on the latitude and longitude entered under the Emulator Control in DDMS. Figure 21 shows the location settings.

Figure 21. Location settings in DDMS
Location settings in DDMS
Location settings in DDMS

Run on a device

If you have an Android phone connected, run the application on your device as described in the "Run the application on an Android phone" section. As shown in Figure 22, the screens will look similar to those on the emulator. The police search should return a police station near your current location.

Figure 22. Application running on device
Application running on device
Application running on device


In this article, you learned how to combine PhoneGap and Mobile Dojo to rapidly create a hybrid mobile application for Android that looks and behaves like a typical Android application. You could write it quickly because we used HTML and JavaScript instead of Java. Given that the web code remains the same across all mobile operating systems, this hybrid application could be easily built for iOS and Blackberry with minimal effort.

Stay tuned for Part 2 in this series, which will cover writing a mobile insurance application using Dojo and PhoneGap.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Web development
ArticleTitle=Mobile application development, Part 1: PhoneGap and Dojo Mobile on Android