PhoneGap for Windows Phone Dissected

This is not a postmortem, per se, as we will continue to develop and support PhoneGap for Windows Phone, consider this more of a milestone postmortem. We are reaching the end of our engagement with Microsoft so I thought I would take the time to reflect on the overall experience of bringing PhoneGap to Windows Phone.  PhoneGap is turning 1.3.0 today, so here is a look back at the journey here, what I have seen along the way, and a summation of where we are.  I will start by doing some (cross-platform/market ) comparisons of the tools, marketplace, and devices, and finish up with a comparison to developing PhoneGap applications on other platforms.

The Tools

Building apps for Windows Phone requires the use of Visual Studio, and early on we chose to use C# as the development language for all native functionality. Visual Studio is a very capable tool and the out of the box templates it gives you to make a Windows Phone app are very well documented, easy to understand, and a great help in getting started. Having developed app/websites in Visual Studio since VS6, I felt right at home.

Writing in C# was a refreshing change from Objective-C, spending less time worrying about memory management and [awkward syntax] and focusing on the task at hand. I knew less about the Silverlight portions of the Windows Phone SDK, however this does not get in your way, as there is no real difference between the code you write, and it is only in the WPF/XAML that this comes into play. PhoneGap apps for Windows Phone have one PhoneApplicationPage and the majority of the work is done in the code behind. As with any Silverlight/C# development, you can expect to spend some time dealing with Multithreading, Delegates, Generics, Linq, as well as XAML. This will not affect those of you are developing PhoneGap apps unless you choose to dig into plugins, or supplement the PhoneGap functionality with some custom functions.


Visual Studio templates are easy! You can turn any project into a template just by selecting File→Export Template. With a little research, you can find the special template identifiers that are automatically replaced for you when the user creates a new project from your template. $safeprojectname$ is automagically replaced with the name the user has chosen, minus any special characters or spaces. $guid1$ will generate a guid when the user creates a new project from your template. This is how I was able to keep the PhoneGap starter project pretty simple. It is an empty project with a .dll containing the PhoneGap functionality, plus a www folder with a starter index.html/master.cs/phonegap.js!

The Marketplace Test Kit

I will cover the Marketplace features in more detail in a bit. Visual Studio for Windows Phone includes a tool titled the Marketplace Test Kit. This provides a simple way for you to test your app in preparation for submission to the marketplace. Automated tests include Capability Validation, Icons and ScreenShots, so you can be sure you have all your resources together in the appropriate sizes and cleanup any references to unused SDKs.

Monitored tests include the ability to check things like launch time, use of the back button and memory consumption. You essentially just start the test which launches your app on the device, and monitors it while you put it through it’s normal paces.

There is also a handy list of manual test cases which provide textual descriptions of specific use cases you should test.

The SDK + APIs

The level of functionality that is available within a Windows Phone app is consistent with other device SDKs. APIs like Contacts vary greatly from platform to platform, and Windows Phone is no different. Windows Phone has multiple contact associations for managing the same Contact entry within Facebook, or Twitter, or LinkedIn, but this is mostly transparent to a PhoneGap app as the PhoneGap API does not expose this functionality.

[Sidenote] IE9, the browser that comes with Windows Phone Mango, has implemented the javascript geolocation API exactly to spec, so there was no need to implement anything in PhoneGap to make this work.

The Emulator

The SDK comes with an emulator suitable for testing your apps during development. It does a good job of showing you how your app will run on a device and provides the abilty to simulate orientation changes, as well as accelerometer and geolocation changes. The geolocation tab allows you to define a route on a map by dropping pins and then simulate moving the device from point to point so you can be sure that your geolocation events are being handled correctly without having to jump on a train to test your app. ( I wish the other emulators had this feature. )

The emulator runs the exact same binary code as the device, so there is no difference in building for emulator or device.  Remember to always test on the device to measure the actual performance, which is usually slightly slower than the simulated version.  Interestingly, in some cases the performance on the device seemed to be better on the device, mainly when numerous screen/DOM updates were happening, the emulator seemed to flicker, while the device rendered things smoothly.

The Devices

During development I worked with 3 different devices. The Samsung Focus was my favorite, and is the one I am using currently. It is a very capable device, lighter than my iPhone 4 and the one of the few non-iOS devices where I could change the sim-card or battery without feeling like I was destroying it. The HTC HD7 is another very capable Mango device, and almost identical to their Android phone, the EVO. The Dell Venue did not feel like it belonged in this century, and I am surprised that any manufacturer could release such a device in a post-iPhone world. From an API-SDK standpoint, there is much better consistency between devices than there is in the Android world, where every device + carrier seems to have their own slight changes.

The Browser

Windows Phone Mango includes IE9 as the browser, which is also responsible for rendering the document in the WebBrowser component used by PhoneGap. IE9 is by far Microsoft’s most compliant browser to date, and is virtually identical to the desktop version from a developer standpoint. The JavaScript Engine in IE9 (codenamed Chakra) is greatly improved and code performance ‘feels’ very good. Chakra adds window.onerror which allows you to define a default handler to catch ALL errors that happen in your document. This is a huge help as it only takes on extra : to break your entire application. By redirecting window.onerror messages to console.log, we can see where these errors are happening.

The Layout Engine aka Trident is a vast improvement from the older IEs, however I still have some some gripes. There are no transitions or animations, and DOM updates do not appear to be accelerated. Having to resort to setInterval + incremental style updates on items, while working, is not nearly as fun and easy as being able to simply define the transitions via CSS.

The biggest oversight, IMHO is the lack of touch events. At first I did not see this as a big deal, as I expected to be able to simply map mouse events to ‘simulated’ touch events ( a’la ThumbsJS ). Unfortunately, the mouse events don’t really exist either. It appears that Microsoft’s goal originally was to make existing websites function/render properly on the device. The way it is currently implemented, your document will receive a mousedown event, but as soon as the user moves their finger, the native container takes over the event, and your JS code will simply get a mouseup.

There are several work-arounds that can enable you to handle certain conditions, but generally these methods are hacky, and only useful if you just want to turn off scrolling/zooming of the webpage. Colin Eberhardt did the initial research (blog post here) and discovered how the WebBrowser control’s view stack is defined, and discovered how to prevent the events. I worked from his code to produce an experimental class that will simulate the events in document, and prevent them based on a return value. (source code here) Both of these solutions have a flaw which is, they are completely dependent on the WebBrowser’s current implementation, which is pretty much guaranteed to change in a future update to the OS. Hopefully when said update happens, it will include the ability to prevent scrolling from javascript in the document intrinsically.

The Marketplace

The Windows Phone marketplace is very similar to other platforms. Discovery, et al, can happen in the browser, as well as on the device, or in the Zune software. User’s are authenticated against their Windows Live Id, so being an XBox-Live user already, I was already able to purchase without re-entering my credit card info.

Microsoft has implemented pre-auth permissions like Android, where before purchasing, you can see what permissions the app requires. Although I much prefer the Apple method of prompting on first use, I am okay with pre-auth, but unfortunately it does not work as simply as Android. While you DO define your required permissions in the WMAppManifest.xml file, these values are overwritten by the static analyzer when you submit your app. This is different than on Android, where if you don’t define a permission, you can’t access it, and are blocked at run-time. This unfortunately affects PhoneGap projects, because the PhoneGapLib dll contains ALL the phonegap code, it essentially requires all the permissions, regardless of whether the code is called. I will be making another blog post on a specific work-around for this, involving a minimal PhoneGap library, and manual additions of extra APIs, so stay tuned for that.

The Metro UI

The user interface for Windows Phone has been drastically redesigned, and has received much acclaim for the fact that it does not look like a runt in the iOS litter. Metro does a good job of combining accounts, and contacts into the ‘friends’ tile, and has some great social interaction shortcuts. With updates happening from different accounts and services, the home screen on Windows Phone Mango literally looks alive with activity. Note: There are already PhoneGap plugins for Windows Phone. The PGShare plugin allows your users to share a status update or a link to Windows Live, Facebook, Twitter, and Linked in, all at once. The LiveTile plugin allows you to update the info/images displayed on the application tile on the user’s home screen. This goes way beyond the iOS bubble + number! The Windows Phone PhoneGap plugins are all here:

PhoneGap for Windows Phone

We have managed to implement the full PhoneGap API, and the JavaScript code that you write for other devices will function as expected. On Windows Phone, PhoneGap is incredibly flexible. The API is implemented inside a user-control. This means that you can easily add a little PhoneGap to an existing WP7 app, or if you choose, you can add Silverlight controls to your PhoneGap app. ( I added the AdControl ( Banner Ads ) to SujiQ in under 5 minutes, including signing up for the service, and getting an advertiser key! )  This flexibility should especially interest any Windows Phone developers, or just those coming from a .net background, who are experiencing PhoneGap for the first time.  The rest of us know that this just means we have another solid platform + market where we can easily deploy our PhoneGap apps.

While I prefer working directly in the DOM, if you are set on using a UI framework, you will likely want to use jQuery Mobile, as it is the most IE9 friendly. With the absence of touch events, libraries like SenchaTouch, iScroll simply will not function, although I aim to spend some more of my experiment time in this area.

Get/Fork the source code here:

The github repo also contains a sample project that will help you get started with a dedicated page for each API.  The Camera/Capture demos are exceptionally cool because they show how easy it is to snap a picture from the Camera and stick it in the DOM.  With a little work you should quickly be able to combine this with the File API demo page and make a simple app that uploads a picture taken from the Camera.  All without writing any C# code, without having to know anything about the Windows Phone UI classes, XAML, ... and it will work on iOS, Android and Blackberry without modification.  Sounds pretty powerful to me.

The commit history will say the same thing, but for those that like the high level,  I have to give Sergei Grebnov a huge tip of the hat for his awesome contributions along the way.  Sergei is responsible for a LOT of PhoneGap for Windows Phone.

Happy 1.3.0 and beyond!