PhoneGap/Cordova Template/Tutorial for Sharing Code Between Platforms

Sometimes the hardest part of trying a new technology is the initial configuration process. This post is intended to help developers in getting started with PhoneGap more quickly cross-platform. I’m working on some pre-configured project templates and the first one is included with this post.

Basic PhoneGap Project Template

This first template contains preset project templates for iOS and Android to help make it easier to share source files between IDE’s (XCode and Eclipse). There are a couple of benefits to this. If you are developing strictly for iOS, the process to get started is pretty easy (using XCode on Mac), however, more often than not you will want to develop for Android as well and need to make specific tweaks/test etc, so you’ll want to have your development environment set up. By using this template you will benefit by being able to skip all the tedious steps beyond 1 and 2 here since my template will already contain the necessary folders and other edits needed already. You just need to ensure you have your Eclipse environment set up for Android development first (also see Setting up your Development Environment below). It is also assumed that you have installed PhoneGap/Cordova and run the dmg inside the iOS folder for XCode. See below for detailed links on that as well before going further if you have not done this already.

Note: There is one other new option for creating/building/testing your projects for the different platforms from the command line completely outside of the IDE’s. Details on using these command line tools can be found here.

Setting up your Development Environment
Setting up your IDE’s for development with PhoneGap has been covered in other places so I’ll include the links here in case you have not taken those initial steps and are starting from scratch:

• Detailed Starting from Scratch Tutorial
• Download Cordova
• Install Cordova for iOS
• Set up Eclipse for Android Development – IMPORTANT NOTE: You should only should have to do steps 1 and 2, the template includes the other steps in the android-project template.

Template Structure
The basic project structure looks like this:

Description

- the android project for Eclipse to import
- the iOS project for XCode to open
- the shared src that is symbolically linked to from within the two projects above

Linking src folders
To make edits to shared source files across IDE’s (versus lose changes when jumping from XCode to Eclipse), you’ll need to perform one additional step after downloading the template. You will need to create a symbolic link to map the src folders within the separate projects to the shared src folder in the template root as shown in the above. Open a terminal window and use the ln -s command to do a symbolic link by entering the full paths from the downloaded project src folder to the www/src folder within each of the iOS and Android projects respectively. For instance, here’s how mine looked:

hollyschinsky$ ln -s /Users/hollyschinsky/Documents/HollysProjectTemplates/PhoneGapTemplateProject/src /Users/hollyschinsky/Documents/HollysProjectTemplates/PhoneGapTemplateProject/ios-project/PhoneGapTemplateIOS/www/src

Importing the Template Projects

iOS / XCode IDE
In XCode go to File | Open and locate the .xcodeproject file located in the ios-project folder:

Android / Eclipse IDE
Again, this article assumes you have your Eclipse environment set up for Android, if you have not done that yet, see this link. Also, you may want to check out this link on the PhoneGap getting started wiki.

Now to use the android-project, go to File | Import, then expand the General node and choose Existing Projects into Workspace as shown here:

Next make sure Select root directory is selected in the dialog that follows, then select the android-project from the template as shown:

When you want to run the project, right-click on the root project in Eclipse and select either Run As or Debug As and then the Android Application option. If you’ve never set up an emulator or do not have an Android device connected, then you will need to set up an emulator or virtual device to use as the target. More details in the next section if needed.

Setting up an Android Virtual Device
You can use the AVD (Android Virtual Device) Manager from the Eclipse Window menu to set up or manage your virtual devices (part of the Android Eclipse plugin you should already have installed). You should then be able to edit your Debug or Run Configurations Target to use the virtual device.

When the project is running successfully in the emulator, you should see something like this:

IMPORTANT NOTE: This project assumes an Android target platform OS level 2.2 (API 8), the recommended minimum, so if you get an error about platform level, you probably don’t have that SDK installed. In that case you can either update the project.properties file to target a different API level, or use the Android SDK Manager to install more versions via the Eclipse Window menu (again part of the Android Eclipse plugin).

Additional Notes

• When first beginning development with PhoneGap/Cordova it’s important to note there are separate JavaScript files for each platform. So there’s a cordova-1.9.0.js for iOS (or whatever the current version is), and a similarly named cordova-1.9.0.js file for Android, so it could be confusing if you’re not aware of this. My template already includes the correct one for you in each project. One quick way to tell the difference is by looking at the file sizes. For instance in the cordova-1.9.0.js case, the iOS version is 168k and the Android is 182k.
• If this is your first time trying out PhoneGap development, you may want to know more about how it actually works with the native Java or Objective-C to load the index.html file. In your Eclipse project, there’s a src folder in the root (not the same as the src folder of the template root or www folders, keep in mind), but that includes the default Java activity file needed for an Android project, and is essentially the boostrap for the project. Here’s a screenshot showing the Android project structure with the Java activity shown in Eclipse to illustrate:

In XCode, the Objective-C code for loading the index.html is within the AppDelegate.m class, for instance:


NOTE: The native code is already set up to point to the proper files in the template, the above is for informational/curiosity purposes only :).

• If you’re confused about why you see PhoneGap/Cordova used interchangeably, see this post.
• The main www folder required for PhoneGap is set up in a different location per platform by default. If you’re developing for Android the www folder is within the assets folder. For iOS it’s located in the root of the project. Here’s a screenshot showing the expanded projects to illustrate:

Template Download

The template is available on my github account located HERE…