Linked Source Files Across PhoneGap Projects on OSX

If you are manually building PhoneGap projects across multiple platforms, managing source files can sometimes become a little bit tricky. If you are building for Android, you need a project within Eclipse. If you are building for iOS, you need a project within Xcode. If you are building for both, you need to make sure that the code in the Eclipse project is in synch with the code in the Xcode project so that the platform-specific apps are in parity with each other.

Keeping the project source code in synch can be achieved using manual copy/paste between projects, but this is messy and error prone. The synchronization can also be scripted using ANT or other scripting language, but this requires an additional script and/or step in your build process. Although scripting is a reliable process, sometimes you just don’t need the script.

If you don’t want to manually synch things, and you don’t want a script, you can use a symlink to link directory paths. Basically, create a “src” folder outside of each project, and create a symlink reference to the src folder inside of the “www” folder for each project.   Symlinks allow a logical directory mapping, which actually points to another location on the hard disk.

From the command line, you just use the following command:

ln -s source target

To setup your project, first create your directory structure.  I created a parent folder for the project. Inside of that folder, I created a “project-ios” folder, “project-android” folder, and “src” folder.   The “src” folder will contain the shared HTML/JavaScript for the application.   The “project-ios” folder will contain the Xcode project, and the “project-android” folder will contain the Eclipse project.

Project Structure

Next, create the actual iOS and Android projects inside of these folders, following the normal setup instructions:

Once you have set up both projects, you’ll need to configure the symlinks.   Put a copy of the “index.html” file into your “src” directory.  Next, go to the “www” directory for each project and delete the “index.html” file to remove any ambiguity or chance for error.


The phonegap.1.4.1.js files are platform specific.  The Android version will not work with iOS, and the iOS version will not work with Android.

Next, navigate to your root folder that contains the “src”, “project-iOS”, and “project-Android” folders. Here you will create the actual symlink references.   When doing so, be sure to use the full path to the source and target destinations.  You will need to create a symlink reference from the “src” directory to “project-ios/www/src”, and a symlink reference from the “src” directory to “project-android/assets/www/src”.

If you try to use a relative path from your current location, it will give you errors and a massive headache.     You can use “pwd” to get a reference to the full path of your current directory.

Here are the commands that I used on my system, where the root directory is “/Users/triceam/Documents/dev/phonegap-sharedsource”:

[bash]ln -s /Users/triceam/Documents/dev/phonegap-sharedsource/src/ /Users/triceam/Documents/dev/phonegap-sharedsource/project-ios/www/src
ln -s /Users/triceam/Documents/dev/phonegap-sharedsource/src/ /Users/triceam/Documents/dev/phonegap-sharedsource/project-android/assets/www/src[/bash]

You can see this in my console in the image below:

Create Symlinks

This will create logical links to the root “src” folder, which can be treated like any other directory structure.

Symlink References

In both Eclipse and Xcode, this will show up as a normal folder.  Any edits in one IDE will show up in the other IDE since they are pointing to the same physical directory on the hard disk.

Content in Eclipse & Xcode

Next, you’ll need to update the PhoneGap projects to point to the shared index.html file.

In the Eclipse project, open your main Android activity and change the call to super.loadUrl to refer to the index.html file inside of the linked “src” directory in the onCreate method.

[java]public void onCreate(Bundle savedInstanceState) {

In the iOS project, open AppDelegate.m. You’ll also need to update it to reference the index.html file inside of “src”. You’ll just need to edit the start page to “src/index.html” inside of the function: (BOOL) application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions

[objc]self.viewController.wwwFolderName = @"www";
self.viewController.startPage = @"src/index.html";[/objc]

Also, be sure to update the link inside of “src/index.html” to point to the project-specific PhoneGap JavaScript files in the parent directory “../phonegap-1.4.1.js”
(they are not inside of the linked folder):

[html]<script charset="utf-8" type="text/javascript" src="../phonegap-1.4.1.js"></script>[/html]

Adobe’s View of Flex & Future Commitment

Adobe has just published a white paper detailing current views and future commitments to Apache Flex. Included topics are contributions to Apache, commitments to the Flash platform, and commitments to Adobe customers.   I strongly recommend that all Flex developers and project stakeholders read this:

Or, download and read the pdf version.

Here’s an excerpt:


Adobe believes that Flex is the best solution for enterprise and data-centric application development today and is moving Flex into a community-driven open source project to ensure the continued development and success of Flex for years to come. We are currently in the process of contributing the core Flex SDK, automation libraries, AIR SDK binaries, and documentation to the Apache Flex Project. We will also be contributing Falcon, Falcon JS, Mustella, and BlazeDS.

In addition to these contributions, Adobe is providing a team of full-time Flex SDK engineers who will contribute to and support the Apache Flex Project. These Adobe engineers will work directly with the highly skilled Flex developer community to maintain, support, and evolve the Flex SDK. We remain committed to enabling the success of all existing and new Flex projects.

“What is PhoneGap?” & Other Common Questions

While looking at the analytics for my blog, I’ve recently started to see a lot of search phrases similar to “what is phonegap?”, “how does a phonegap app look?”, “how to get started in phonegap?”, among many, many others.   In this post, I hope to shed some light on some basic questions to help you understand and start working with PhoneGap.

In case you don’t feel like reading the whole thing, here are quicklinks to each question:

What is PhoneGap?

PhoneGap is an application framework that enables you to build natively installed applications using HTML and JavaScript.  The easiest way to think of PhoneGap is a web view container that is 100% width and 100% height, with a JavaScript programming interface that allows you to access underlying operating system features.  You build your user interface using traditional web development skills (HTML, CSS, & JavaScript), and use the PhoneGap container to deploy to different application ecosystems and devices.  When packaged for deployment, the PhoneGap application is a binary distributable file that can be distributed by the “normal” application marketplaces (iTunes, Google App Market, Amazon Market, etc…).

PhoneGap is 100% open source, and also goes by the Apache name “Cordova”.  You can read more about Apache Cordova project status at:

PhoneGap can be used to build applications that target multiple platforms, including Apple iOS, Google Android, Windows Phone, BlackBerry, HP WebOS, Symbian, and Bada.

You can read more about the supported platforms and their supported features at

How does a PhoneGap application typically look?

Since the UI rendering engine is the mobile device’s web browser, PhoneGap applications can literally look like anything.   You can use standard HTML & CSS to make it look like a normal web page, you can use a UI framework like jQuery UI, Kendo UI, SenchaTwitter Bootstrap, or Skeleton (or any other HTML/CSS/JS user interface framework). You can also use CSS styles/themes to make your web content look like native apps, such as iUI to mimic iOS or Android, or bbUI  to mimic BlackBerry.

PhoneGap applications can have static UIs based on normal HTML, or can have dynamic & interactive experiences developed using JavaScript.   It depends upon the specific application, user experience design, target audience, and use cases to dictate how a PhoneGap application will appear.

PhoneGap applications can use pinch/zoom gestures to zoom in & out, or you can lock the viewport scale using the viewport metadata tag.   You can have the page scroll using normal browser behaviors, or you can use a library like iScroll to enable touch-based scrolling of specific container elements.

There really are lots of ways to create a user interface with HTML, CSS & JavaScript, so there really isn’t any “typical” look.   If you do not apply any CSS styles at all, then all user interface elements will use the operating system/browser default for that specific platform.   This includes buttons, links, and color/highlight states.   This behaves in the exact same manner as the operating system’s default web browser.

How do I get started in PhoneGap?

Getting started in PhoneGap is easy.   For 90% of a PhoneGap application, all you need is a text editor.  PhoneGap also integrates with device-specific development environments very easily.   You can view “getting started” guides for all application platforms at the links below:

When developing PhoneGap applications, just keep in mind that you are running code inside of a web browser instance.   You develop your applications using HTML and JavaScript, not native code, so you don’t need anything special.   In fact, I personally do most of my development on the desktop using an HTML editor and the Chrome browser.  When I need device-specific functionality, or I need to test on a device, then I switch over the the device-specific environments.

How do you debug PhoneGap applications?

Debugging PhoneGap applications can sometimes be the trickiest part of development.   If you are testing on a physical device, you can’t always get access to JavaScript exceptions when they happen.   There are a few strategies for debugging PhoneGap applications.

Develop as much as possible on the desktop browser

Since PhoneGap applications are written with HTML, CSS, and JavaScript, you can develop most of them using any HTML editor and debug them within a desktop web browser.  The latest versions of all major web browsers (including Chrome, IE, Firefox, Opera and Safari) provide rich debugging features. In the developer tools for the browsers, you can inspect HTML DOM elements, inspect CSS styles, set breakpoints in JavaScript, and introspect into memory & JavaScript variables.   You can learn more about the desktop browser development tools at:

Once you build the main aspects of your application using desktop tools, you can switch over to a device-specific environment to add device-specific behavior and integrate with PhoneGap APIs.

It is imperative that you test your applications on actual devices!   Actual devices will have different runtime performance than desktop browsers and simulators, and may unearth different bugs/issues including API differences and different UX scenarios.

Debug With

PhoneGap provides a hosted service that allows you to perform remote, on-device debugging through  This uses the Weinre (Web Inspector Remote) debugging tool to allow you to remotely inspect the DOM, resource loading, network usage, timeline, and console output.   If you have used any of the developer tools listed above, this will look very familiar.  You will not be able to set breakpoints on the mobile device, but it is certainly better than nothing at all.

Remote Web Inspector Through iOS 5

There is a little known undocumented API introduced in iOS5 that allows you to perform remote debugging through the iOS5 Simulator.  You just need to enable remote debugging
[objc]- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
// Uncomment to enable remote debugging
[NSClassFromString(@"WebView") _enableRemoteInspector];


Then launch the application in the desktop iOS Simulator. Once the app is running, open a local Safari instance to: http://localhost:9999/. This will launch the remote debugger, complete with breakpoints and script introspection.

More Debugging Info

You can also read more about debugging PhoneGap applications at:

How do you architect PhoneGap applications?

You generally architect PhoneGap applications the same way that you create mobile web experiences. The difference is that the initial HTML assets are available locally, instead of on a remote server.   The PhoneGap application loads the initial HTML, which can then request resources from a server, or from the local environment.   Since PhoneGap is based in a browser, it behaves exactly as you would expect a web browser to behave.  You can load multiple pages; however, keep in mind that once you load/unload a page you may lose any data that is stored in memory via JavaScript.   PhoneGap also supports the single-page web experience model. I strongly suggest using the single-page architecture approach.

Single-Page Architecture

A single-page architecture refers to the practice of having a single HTML page that dynamically updates based upon data and/or user input.  You can think of this as closer to a true client/server architecture where there is a client application (written with HTML & JS) and a separate server structure for serving data.  All client-side application logic resides in JavaScript.  The client application may request data and update its views without reloading the current web page.

Using a Single-Page architecture allows you to maintain data in-memory, in JavaScript, which allows you to have a stateful, yet dynamic user interface.   You can read more about single-page architectures at:

PhoneGap applications can be architected with any of the common JS architectural frameworks, including Angular, Ember, Backbone, Mustache, etc…   Fellow Adobe evangelist Christophe Coenraets has some great content on these topics.

How do you get PhoneGap apps on devices and into application ecosystems?

PhoneGap applications can be deployed using the same guidelines for native applications for each given platform.   You must follow the rules of each hardware platform/vendor, and there is no way to get around that.     You can compile the executables for each platform yourself using each platform’s specific build process, or you can use to compile them for you. is a hosted service that will compile platform-specific application distributable files for you.   In either case, the output of the build process is a platform-specific binary file: IPA for iOS, APK for Android, etc…   You can read more about distributing to various application ecosystems, and each system’s signing/certificate requirements at:

What is the difference between PhoneGap and AIR?

The most fundamental differences between PhoneGap and AIR is that you develop AIR applications using tools rooted in the Flash Platform (Flex, Flash, ActionScript, MXML), and you develop PhoneGap applications using HTML, CSS, & JavaScript.   AIR applications use the AIR runtime, which allows you to have a single code base, with the exact same expected behavior across all supported platforms.   PhoneGap applications run inside of the native web browser component for each supported platform.  For this reason, a PhoneGap codebase may behave slightly different between separate platforms, and you will need to account for this during your development efforts.

Air applications can be built for iOS, Android, BlackBerry Playbook, and the desktop (mac and windows), with future support for Windows Metro (Windows 8 mobile interface). You can read more about AIR’s supported platforms at:

PhoneGap applications can be built for iOS, Android, BlackBerry, Windows Phone 7, HP WebOS, Symbian, and Samsung Bada. You can read more about PhoneGap’s supported platforms at:

ActionScript has strongly-typed objects and supports classical inheritance programming models. AIR applications can also be built using the Flex framework, which allows you to rapidly build enterprise-class applications.   Components in AIR applications are logical objects that have behaviors, properties, and a graphics context.

JavaScript-based applications support prototypal inheritance, and have numerous open-source frameworks/tools that can be used.   HTML/JS applications are all visualized through HTML DOM elements.  HTML interfaces can be created through basic string concatenation or JavaScript templating, but in the end you are really just creating DOM elements that have properties and styles.

There are some fundamental difference in the syntax of building these applications, however the basic concepts of interactive design and interactive development are identical.   Both platforms have valid strengths, which I could write about ad nauseum… I’ll save that for another post.

Where to go next?

Go download PhoneGap and get started at: or check out what other people have been building in the PhoneGap showcase at:

Fun Apps w/ PhoneGap

Here’s a silly/fun app I built ‘after hours’ using PhoneGap.   It is a children’s drawing app built entirely with the HTML5 Canvas element, using a PhoneGap wrapper, targeting the iPad.  I was inspired by magnetic drawing toys that I often use when drawing with my daughter, and this was really, really easy and a lot of fun to build.  I used the exact HTML5 Canvas brush image/sketching technique that I have previously demonstrated – the only change is that I added the new UI style elements and added support for multiple touch points. Otherwise, the drawing logic is identical.

Lil’ Doodle is a great new iPad application for entertaining both you and your children! If you know how to use a children’s magnetic drawing toy, then you know how to use Lil’ Doodle. Pick a “pen” shape, and start doodling. Your imagination is your only limit. If you want to erase everything and start over, just use the slider at the bottom. Doodle and have fun!

Using the HTML5 Canvas inside of PhoneGap has great performance on iOS, and building the application using purely HTML, CSS, and JavaScript made it incredibly simple. After I wrote the core drawing engine for a previous blog post, I whipped up the UI in one evening, and then started user testing with my little beta tester.  She found some issues that I had overlooked, and a few days later I submitted it to the app store.

…and yes, she really does play with it:

The app is currently available for iPad devices on iTunes – I’m about to start researching/testing performance on other platforms, so maybe soon it will be out in other ecosystems… we’ll see.   You can get it now at:


Bleeding Edge HTML5, WebRTC & Device Access

The world is changing… and oh my, it is changing fast.   In the not-too-distant future, many capabilities that were exclusive to plugin-based content will be accessible to the HTML/JavaScript world without any plugin dependencies.   This includes access to media devices (microphone and camera), as well as real time communications.   You might be reading this thinking “no way, that is still years off”, but it’s not.

Just last night I was looking at the new webRTC capabilities that were introduced in the Google Chrome Canary build in January, and I was experimenting with the new getUserMedia API.   WebRTC is an open source realtime communications API that was recently included in Chrome (Canary, the latest dev build), the latest version of Opera, and soon FireFox (if not already), and is built on top of the getUserMedia APIs. Device access & user media APIs aren’t commonly available in most users’ browsers yet, but you can be sure that they will be commonplace in the not-so-distant future.

Below you’ll see a screenshot of a simple example demonstrating camera access.

You can test this out for yourself here:

Note: This requires the Google Chrome Canary Build.

The beauty of this example is that the entire experience is delivered in a whopping total of 17 lines of code.   It uses the webkitGetUserMedia API to grab a media stream from the local webcam and display it within a HTML5 <video> element.

function load() {
var video = document.getElementById(‘myVideo’);
if (navigator.webkitGetUserMedia) {
function(stream) { video.src = webkitURL.createObjectURL(stream); },
function(error) { alert(‘ERROR: ‘ + error.toString()); } );
} else {
alert(‘webkitGetUserMedia not supported’);
<body onload="load()">
<video autoplay="autoplay" id="myVideo" />

While this example is really basic, it is a foundational building block for more complicated operations, including realtime video enhancement and streaming/communications.    Check out this more advanced example from, which applies effects to the camera stream in real time:

Note: This also requires the Google Chrome Canary Build.

You can read more about WebRTC, get demos, and get sample code at

If you want to read more about some of the new “Bleeding Edge” features coming to the web, check out this slide deck by Google’s Paul Kinlan.   You can also read more about the getUserMedia API from Opera’s developer site.