Setting up a PhoneGap project for Android in Eclipse

2012-08-19

It’s pretty straightforward to set up a PhoneGap project for Android in Eclipse. You need to make sure you’ve got Eclipse Classic, the Android SDK, the ADT plugin for eclipse and PhoneGap.

Open Eclipse and choose “New Project” from the “File” menu. There should be an Android folder so select “Android Application Project” from under it and click “Next”. Give your app and project a name then provide a package name (usually your domain backwards, e.g. com.alk3my.bestbooks). Choose the SDK version you would like to target, you may want to read my post on android publishing considerations to help decide which version to target. Click “Next” to carry on.

Next eclipse can help you make your launcher icon. Choose a suitable image and play with the options before proceeding. On the next screen you will see a default option to create an Activity, leave it on “BlankActivity” and click next. Leave the defaults alone on the next screen and make sure there is no Hierarchical Parent. Finally click “Finish”!

In the assets folder of your project, create a “www” directory. This is where all your HTML/CSS and JS will go. Copy the PhoneGap JavaScript file into the root of this folder and also copy the PhoneGap .jar file into the “/libs” folder (should already exist at the root of your project and will have an Android .jar already). Next copy the “xml” folder from PhoneGap into the “/res” folder of the project.

Now you need to make sure the PhoneGap .jar is in the Build Path of your project. Right click on the “/libs” folder, choose “Build Path” and then “Configure Build Path…”. With “Java Build Path” selected, click on the “Libraries” tab and then “Add JAR” to add the PhoneGap library. You may need to refresh the project to see the JAR (F5).

Next open up the “MainActivity.java” file from the “src” folder and import “org.apache.cordova.*;”. You can remove the “android.view.Menu;” import and the “onCreateOptionsMenu” override method too. Change your MainActivity class to extend DroidGap instead or Activity. Finally your “onCreate” override method should look like this…

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); super.loadUrl("file:///android_asset/www/index.html"); }

So now it’s on to the AndroidManifest.xml file. Within the manifest element you need to paste the following…

<supports-screens android:largeScreens="true" android:normalScreens="true" android:smallScreens="true" android:resizeable="true" android:anyDensity="true" /> <uses-permission android:name="android.permission.VIBRATE" /> <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.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.RECEIVE_SMS" /> <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" /> <uses-permission android:name="android.permission.READ_CONTACTS" /> <uses-permission android:name="android.permission.WRITE_CONTACTS" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.BROADCAST_STICKY" />

This gives your application all the hardware/API permissions you’ll need for any app but it’s necessary to tighten this up before publishing your application. Remove anything that isn’t required or your application will be limited to a subset of devices that support all of these permissions. You’ll also give the user a lot to worry about as the installer will ask them about all of these permissions.

Add the following attribute to the “activity” element; android:configChanges="orientation|keyboardHidden. This stops the application exiting when you rotate your device, LOL. You can also add android:debuggable="true"> while developing your application, just remember to remove it later.

I use git for source control and I suggest you choose from one of the many source control options to keep track of your changes (bitbucket has free accounts which is just awesome). You could put the whole project under source control although personally I only put the “www” directory in git. This is because I have intentions to use the same (well very similar) code to release iOS and maybe win mobile versions of my applications. The actual project folder is very static anyways so there will be very few changes throughout development anyway.

Now you’re set, start with an index.html file at the root of the “www” folder and add your HTML, CSS and JS. I suggest testing in Chrome/Safari to begin with as debugging is much simpler and changes are instant as opposed to using the simulator or the actual device. Save those for every now and then and towards the end of the development cycles. A good way to organise your work and bugs is by creating cards on Trello so you know what you should be working on, what you’ve done and what still needs to be done.


Comments: