PhoneGap 3 – My initial experience

PhoneGap 3.0 was released this year in July, but I hadn’t given it a try till a few days back.     I had to start a new PhoneGap project using the latest version (PhoneGap 3.3).
There have been significant changes in the way PhoneGap is installed and project created since PhoneGap 3.0. These changes have been very well documented in the official PhoneGap documentation and various blogs. So installing and PhoneGap 3.3 and creating the first project was a smooth experience.

The problem for me started after the bare minimum project was created. One of the important changes in PhoneGap 3.0 is that every device feature API is a plugin (e.g. contacts, camera etc.) and none of the device APIs are automatically included when you create a project using CLI. You have to add then after you created the project. I was aware of this change and added plugins that I needed using CLI. I then expected to have these APIs available in the application (I created iOS and Android Apps). But they were not.

Beware of sequence of steps

If you go to the CLI docs, you will see the following sequence to create project –

1. Create the App
   e.g. $ phonegap create hello com.example.hello HelloWorld
2. Build the App
   e.g. $ phonegap build ios (in the project folder)
3. Test the App on an Emulator or Device
   You will see PhoneGap Device ready message. At this point no device APIs are available
4. Add Plugin Features
   This is where you add plugins for features like contacts, camera etc.
   e.g. $ phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts.git

The docs then go on to explain how to build the application remotely using PhoneGap Build. But if you want to make changes to the application and open the project in XCode, make changes to use device APIs you just added and run the application in the simulator, you find the device APIs are not available.

It took me some time to realize that after you add any device API plugin, you will have to build the application again. e.g. $ phonegap build ios
When you run this command, PhoneGap creates folder for the OS you have selected (in the above case ios) in the platforms folder and creates platform specific files. So after I added  new plugins and built the application again, PhoneGap added  plugin information in the cordova_plugins.js, config.xml and copied plugin file to the platform specific folders.

There are multiple www folders

There is another thing that you need to be aware when you build the application. PhoneGap creates www folder under the project folder and also under platforms folder. For example, in case of iOS, it creates www under platforms/ios and in the case of Android, it creates it under platforms/android/assets. The build command copies content of the www folder under project  to www folders under platforms.

So if you had opened iOS project in XCode and made some changes to html content (in the www folder) and build the application again, all your changes will be overwritten. I think the expectation is that you do not change html content under platforms folders and work with shared html content in the www of project folder.

Issues with PG Android projects

I had relatively smoother experience importing iOS projects in XCode and running in the Simulator than with Android projects. Note that PhoneGap creates two projects for Android app, one CordovaLib and the other one is your application specific. You need to import both the projects. Use File->Import->Android->’Existing Android Code into Workspace’ option.

I tried a couple of test applications using PhoneGap 3.3 and in all the cases I had issues importing Android projects or running them on device/emulator.

In the first case, after importing the projects (app and CordovaLib), Eclipse could not resolve “org.apache.cordova.*” imports in the application project. These classes are defined in the CordovaLib project, but for some reason reference of this project was not added to the application project. I used the option to fix project path in the Quick Fix (on the import statement where error was displayed) to resolve this issue.

When I ran the application,  I got this error  – “Error initializing Cordova: Class not found”. Looking at LogCat, I found Java ClassNotFoundException for “org.apache.cordova.device.Device”.

I decided to build the Android app again. But before that I wanted to remove all references to the existing app. So I deleted (under the PhoneGap project folder) merges/android, platforms/android and plugins/android.json.

I was using the SDK in the latest ADT bundle to build PhoneGap application ($ phonegap build android). I also had the latest SDK without Eclipse bundle. I changed the path to this SDK and built the application again.

Then I rebuilt the application and imported again in ADT. This time all imports were resolved properly and application also ran without any error. I am not sure which of the above actions fixed the issues.

So far I have used only Contacts APIs, but I am hopeful that other APIs will also work fine (after I add plugins). I think the changes done in PhoneGap 3.0 are good –  specifically CLI and the new plugin architecture (code for only those plugins that use are added, unlike earlier versions where all built-in device APIs were added). But some of the changes are so different from the earlier workflow that it is a bit confusing in the beginning.

-Ram Kulkarni