Over a million developers have joined DZone.

Build Native Mobile Apps in HTML5: PhoneGap from Start to Finish

DZone 's Guide to

Build Native Mobile Apps in HTML5: PhoneGap from Start to Finish

· Mobile Zone ·
Free Resource

PhoneGap is an HTML5 app platform which allows you to develop an application in HTML5 and run it as an native app on your mobile device. PhoneGap does this by running the application in a web browser control in the background. So when the user starts navigating trough your application, PhoneGap will intercept this and navigate to the files which are stored locally on the phone. This way there is no need to have an connection to the internet to run the application. But PhoneGap offers more then only building an HTML5 app. Because most of the HTML5 specifications aren’t implemented in mobile browsers yet, PhoneGap provides an framework, which allows you to access features of the mobile device. For example the camera, file system, contacts, …

Because all these features are OS depended (even device depended sometimes, certainly for Android), there is for every OS an different implementation of the PhoneGap framework. This is because the JS framework which is provided will make calls to a dll (in case of Windows Phone), .jar (in case of Android), …to access the specific features of the mobile device. An overview of all the features can be found here. It gives you also an overview on which platforms the features are supported. The documentation of the API can be found here.

Getting started

Because I am an .NET developer, my starting point will be developing an PhoneGap application for Windows Phone. Further on, I will show how you can reuse your code to target other platforms. The first things you need so we can get started is:

  • The Windows Phone SDK (This will install everything you need to develop a Windows Phone Application. Incl. Visual Studio if it isn’t installed on your computer.)
  • The PhoneGap SDK (The 1.6.0 is already released, but I had some issues with it so I recommend to use the 1.5.0 version for now)
    • The above link is an zip file. When downloaded, extract this file
    • In the extracted folder, navigate to phonegap-phonegap-<xxx>/lib/Windows and copy the following files:


    • Navigate to C:\Users\<UserName>\Documents\Visual Studio 2010\Templates\ProjectTemplates\Silverlight for Windows Phone and past the files of the previous step in here. (If the folder Silverlight for Windows Phone doesn’t exist, Create it)

Now, when we start up Visual Studio, we will see the PhoneGap templates appear under the Silverlight for Windows Phone folder.


Developing a PhoneGap application

Now everything is installed, we can start to develop our application. I’ll choose for the Cordova-1.5.0-Starter, this way I’m using the almost latest version of PhoneGap and the framework is already referenced. This will result in the follow structure.


In the GapLib folder we will find a dll. This dll is used to provide access to the native features of the phone. This way we can call for example the camera trough the PhoneGap JS framework. This framework is present in the www folder. This is the API we will use in our application.

All files we want to use in out PhoneGap application need to be added to the www folder. When the PhoneGap application starts up, the first thing it will look for is the index.html file. So make sure it’s always present in the www folder. One of the first lines in the index.html file is the following:

<meta name="viewport" 
          , height=device-height
          , initial-scale=1.0
          , maximum-scale=1.0
           , user-scalable=no;" />

This makes sure the application is always shown maximized and uses the whole view port.

If you want to make use of the PhoneGap functionalities, you can do this once the device ready has fired. This event gets triggered once all PhoneGap functionalities are loaded.
// once the device ready event fires, you can safely do your thing!
function onDeviceReady()
    console.log("Device ready, you can now access the PhoneGap library.");


Deploying to other platforms

You have two ways to deploy your HTML5 application to other platforms. One is to install the environments of the other platforms and including your www folder in the PhoneGap template of the other platform or use the PhoneGap build service. In both cases you need to make sure the Cordova.js file of the specific platform is referenced. This means if you include the www folder of your windows phone application into the template of an android application, you need to use the Cordova.js file which is provided by the template and not the one you used for Windows Phone)development. If you do so, you will notice the device ready event will not fire and the PhoneGap functionality won’t work. If you are working with jQuery mobile, you can get page navigation error when navigating with jQuery mobile.

When using the PhoneGap build service, the first thing you need to do is creating an account. Once you have this, you can create an new application. Here you need to provide the following:

  • The name of the application

  • Choose upload an archive or index.html file

  • The file you need to provide is a zip of your www folder where your application is present. Note: make sure the Cordova.js, Cordova-1.5.0.js or phonegap.js file aren’t present in the zip. Otherwise the correct version of these files for the specified platform, aren’t included. In that case, your application might not work on the other platforms.

  • When the file is uploaded and you click on create, you can let the build service do his magic. After some minutes, you will have the possibility of downloading the packages for the other platforms.


The build service supports the following platforms:

  • iOs

  • Android

  • Windows Phone (very recently)

  • Blackberry

  • webOS

  • Symbian


The PhoneGap API makes it easier to build your native mobile application once (in HTML) and deploy it to multiple platforms. This is a cheap way if you want to provide native apps in several platforms whiteout building it from scratch in his native language. Of course, you can’t expect that the PhoneGap has the same performance as your real native app would have. Also not all functionality is fully supported on every platform, so make sure you check this before implementing it in your application.

The last thing I want to point out is the experience you get of this kind of application. Because this targets multiple platforms, it can’t provide the platform specific experience like transitions when navigating, the styling, … This is one of the compromises you need to make if you want to reuse your code.



Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}