Over the last month and a bit, Nitobi has been working closely with Microsoft to bring PhoneGap to WP7 devices. I am happy to say that it’s now here, and ready for beta exposure.

The Genesis of PhoneGap for Windows Phone 7

Our starting point was the excellent work of Matt Lacey, who created the initial project and did the initial exploration of device functionality. The upcoming Windows Phone Mango update to devices brings a rich set of HTML5 features and IE9 to the device.

Thanks to Microsoft sponsorship, Sergei Grebnov has been making contributions to the code and has implemented the MediaCapture and Camera APIs. This is Sergei’s first foray into PhoneGap, but he has proven to be a valuable asset to the project and was up to speed quickly.

Nitobi has dedicated two developers to the project, myself and Herm Wong. We’ve been busy dusting off our Sliverlight+C# skills and implementing the other APIs. ( the infamous Shazron has also jumped in just this week ) 

Here’s the outcome!

Some code here : https://github.com/phonegap/phonegap-wp7

Some more info here: http://bit.ly/PhoneGapMangoIntro

What You’ll Need to Get Started

So you want to get on it, enough talk? You will need Visual Studio 2010 with the “WP7 SDK” : http://create.msdn.com/en-us/home/getting_started installed (the free express version works fine )
Detailed instructions will be posted shortly as a getting started guide on PhoneGap.com, in the meantime :

• fork/git or download/unzip the repo to your harddrive
• copy the file GapAppStarter.zip to the folder : My DocumentsVisual Studio 2010TemplatesProjectTemplates
• Launch Visual Studio 2010 and select to create a new project ( PhoneGapAppStarter should be listed as an option, give it a name )
• Right-Click on the solution and select Add->Existing Project, and add the project : frameworkWP7GapClassLib.csproj from the downloaded repo
• Right-Click your main project and “Add Reference” to the WP7GapClassLib project
• build and run!

Where Are We ? What APIs Are Done?

Here’s an overview of where we’re at:

• Accelerometer
• Camera
• Compass (unit testing is waiting on us having a device that supports compass)
• Contacts
• Events (partial, still underway)
• GeoLocation
• MediaCapture
• Connection
• Notification

These have all been implemented per the spec, and function as expected with some quirks being added to the documentation as you read this.

The ‘deviceready’ event is fired on startup, and like other device platforms, is the signal that you can begin making PhoneGap API calls.
The GeoLocation API did not require any work, as IE9 implements the spec as defined by W3C.

Still to come :

• File
• Storage

How Does it Work? A peek under the hood.

PhoneGap-WP7 includes a library project which contains the core functionality, and you reference this project from your own project. Your own project will include the www folder which is where your Gap html/js/css will live. All files in the www folder must be added to the project in Visual Studio and marked as content so they will be packaged with your app when it runs on the phone. We will be releasing a Visual Studio template to allow you to simple select NewProject->PhoneGap-WP7 project and auto-magically be on your way.

Packaging of applications is quite different on WP7. All resources (your PhoneGap js/html/css code in the www folder) are packaged into the XAP as resources but cannot be accessed directly at runtime, so an extra unpackaging step is required.
When the app is first run, all resources listed in the manifest are copied from the binary XAP to IsolatedStorage. IsolatedStorage is a per application File location, similar to a per app Documents folder in iOS. IsolatedStorage is managed per app, so separate applications cannot interact with the same document store. We are working to make this as transparent as possible, so your workflow does not have to change. Build scripts and tooling will eventually take care of the dirty work, but for now you will be building directly from Visual Studio.

After unpackaging the contents of the www folder, your www/index.html file is loaded into an embedded headless browser control. This is essentially the same paradigm as other platforms, except here it is an IE9 browser and not a webkit variant. IE9 is a much more standards-compliant browser than previous IEs, and implements commonly used html5 features like DOMContentLoaded events, addEventListener interfaces, and CSS3. Be sure to use to get the html5 implementation otherwise the browser may fallback to a compatibility mode, and your code will likely choke and die. You should also use in your html .

Gotchas + Known Issues

IE9 does not expose touch events, or even mouse events to JavaScript. The only UI event that is available to your code is the click event. This means that many interfaces that are based on scrolling libraries and a WebKit DOM will not function as expected. The browser control DOES appear to support the CSS value of overflow:scroll, however there is no momentum and the scrolling feels sticky. I have done some quick exploration into exposing mouse events to JavaScript via the container and they do look promising. I will be moving on to this after I completed the Events API so your code can override the back-button and search-button.

IE9 supports localStorage, and sessionStorage, however they are not available to pages that are loaded without a domain. We will be investigating implementing this API ourselves, and managing the storage in IsolatedStorage.

Reporting issues, tracking progress and keeping up to date.

The project code is maintained on github at https://github.com/phonegap/phonegap-wp7, so you can follow it there. Any issues you come across can be filed in the Issue Tracker on github.
As with the other devices, general question can be directed to the PhoneGap mailing list, where the community is ready and waiting to help. For questions specific to Windows Phone 7, please include ‘WP7′ in the subject.

Will PhoneGap for WP7 support plugins?

This was a key focus, as keeping the architecture plug-able is a primary concern, and in my view, where the real power lies.
PhoneGap-WP7 maintains the plugability of other platforms via a command pattern, to allow developers to add functionality with minimal fuss, simply define your C# class in the WP7GapClassLib.PhoneGap.Commands namespace and derive your class from BaseCommand.

PhoneGap exec works in exactly the same way as other platforms :

PhoneGap.exec(callbackSuccessFunction,callbackErrorFunction, PLUGINNAME, PLUGINMETHODNAME, paramObj);

What is Left to Do? How can You Contribute?

Sergei has begun working on the File API, so you can expect full file access to create, modify, delete files as well as upload/download to/from a server.
I am busily trying to wrap up some of the life-cycle events (Events API) so your application can be notified when the app is pushed to the background. I will be looking into exposing mouse events to JavaScript shortly after that.

If you have expertise in any of the Native portions, or JavaScript, you are welcome to fork the repo on github.

Keep in mind: PhoneGap can only accept pull requests from contributors who have signed the CLA so we can make sure that PhoneGap remains open source and free. PhoneGap is dual licensed as defined here : http://www.phonegap.com/about/license

Even if you don’t contribute code back, I/we would love to hear about your experience building with PhoneGap for WP7, good, bad or indifferent. Please direct your kudos, or comments to the Facebook page at http://www.facebook.com/PhoneGap. You are also welcome to contribute to the documentation, and wiki pages, got a great getting started tutorial? Let us know! Want to tell the world about your WP7 PhoneGap app? Let us know!

We will be posting new information to the blog as updates are made, as well as on the mailing list, and PhoneGap.com.

Forever Endeavor

-jm

[Update]

My Blog activity will now happen over at my own site, to relieve the overload on nitobi.com. Check it out at http://www.risingj.com Cheers!

My previous post explained how to get custom launch params so you can respond to different calling conditions, including a call from another app, or Mobile Safari. There is also a very good chance that your app may already be running, so what then?

Handle Open URL

With multitasking, this actually becomes quite likely, because users no longer kill your app, they simply move away from it. Your app is essentially suspended, so you should probably handle the non-launch option as well.

The ApplicationDelegate class defines a method just for this use, all you have to do is override it and hook it into your webView.

Copy the following to your AppDelegate.m and add the function to your js code:

Also, note that you can name your javascript function whatever you want, as long it is the same name that your AppDelegate passes into the webView. I chose to simply keep things clear and called the function "handleOpenURL(urlStr)", but it could just as easily be "appController.handleUrl(urlStr)". As in the previous post, this url is UrlEncoded, so you may need to decode it, depending on your needs.

One cool thing about the handleOpenURL function is that it is easily testable. You can put a link right inside your html to make the call using your protocol and it will be processed by the OS and passed right back to your app. This may not seem useful, but I can foresee situations where it might make sense, like passing info from a ChildBrowser control back to your main app, or completely decoupling your view from your app-controller. … Any other ideas?

I welcome your comments, questions, and suggestions. buy my single =>

I recently reworked some of the launchOption / handleOpenURL code in PhoneGap iPhone.
The commit is here.

You can expect these changes to be included in the next official release 0.9.5 later this month, however these are not considered PhoneGap functions, so I thought I would explain how this all works and save anyone having to wait for the next release.

The custom url schemes are an iOS thing, so it did not make sense to me to include them in the core of PhoneGap, but they are definitely useful, so they needed to be included somewhere.

When you create a new PhoneGap project in XCode, the template spits out a new XCode project containing a subclass of PhoneGapAppDelegate where you can choose to implement whatever you want without worrying about breaking the base classes. I chose to modify the template to make it easier for users to use custom urls. You can also add this functionality to an existing project quite simply.

For a very good description of how to set up the custom url, check out this post.

Once you have set up the plist and added your custom url, you can turn your attention to your app delegate files. First we will look at launchOptions.

Launch Options

In your MYPROJECT_AppDelegate.h add a variable to store the invoked url like this.

Now turning your attention to the implementation file, MYPROJECT_AppDelegate.m, you will need to respond to the didFinishLaunchingWithOptions: message. If you were previously handling applicationDidFinishLaunching: you can safely remove this call, and handle things in the withOptions variant. This is the way the baseClass ( PhoneGapDelegate.m/.h ) functions now, but the template was not updated to reflect the change.

Your didFinishLaunchingWithOptions should look like this:

The above stores the launchOptions url as a string for later use.
Next we will pass it into the UIWebView where our JS app loads, we have to wait for the page to load to do this, but we add it before we call super, so the value will be available when the deviceready event fires in our page.

Now moving to the html/js

Awesome, we have received the launchOptions in our Javascript code, and we can continue on and do something relevant with them.

To test this, open Mobile Safari on your device or simulator ( after having installed your app, and making sure it is not running in the background. )

In Mobile Safari’s address bar enter your customUrl scheme and verify that it launches your app and you see an alert with the freaking launchOptions.

Next up : handleOpenURL

I posted a simple view swapper demo for webkit mobile using XUI + GloveBox.

Want a quick layout for your PhoneGap app? Go and get the code:

https://github.com/purplecabbage/ekiben

Posted my source code for WebKit touch scrolling of flexible sized data in fixed size boxes.

I will be preparing more of a tutorial / demo of this functionality but am way too busy with client work right now. ( I wrote GloveBox on the weekend, and it’s already in use in 3 Nitobi client projects! Expect lots of updates as we put it through the ringer. )

You can get / git / fork the code at http://github.com/purplecabbage/GloveBox
or via svn at

http://code.google.com/p/glovebox/

The choice is yours, but the google code repo will probably be much fresher since I still find myself fighting with git on a regular basis. ( I love github though! Bring on the svn write access … )

Cheers!

So if you want to make an iPhone app using your HTML/CSS/JavaScript skills, what do you use? PhoneGap! obviously.

If you want to add some iPhone native controls, screens, whatever… PhoneGap Plug-ins seem like a fairly easy path, even though they are still largely undocumented, and unknown to most, at least they are somewhat planned.

But what if you have a native iPhone app already, and you want to quickly throw in some phonegap. Before today, there was no easy way to do this because phonegap for iPhone was architected to be the one and only Application delegate. This is the newest use case I have chosen to address.

This approach of breaking PhoneGap functionality into it’s own control space makes some exciting new things possible in the near future. Including:

• Multiple page / view apps where the views are persistent ( instead of having to reload or navigate between pages )
• Sandboxed child apps
• The ability to divide work among multiple developers, without having to constantly keep track of other’s changes.
• Better division of responsibility within code modules ( divide and conquer methodologies ).
• Drop-in functionality, for code libraries, add them to your app more easily, and build up your control library over time.

Introducing Cleavage for iPhone.

First off, you may be wondering about the name. I wanted to stick with the ‘gap’ theme so I started brainstorming on other types of gaps.

At first I considered Diastema as it has a nice ring to it. After thinking on that for awhile I decided it would be best not to alienate phonegap developers as we are predominantly Madonna, Letterman, and Mad Magazine fans. ( What, me worry?)

Other Gaps I considered were :

• Rift – too sci-fi
• Gape – um, too close to Gap
• Fissure – too literal, and weird …
• cavity, chasm, crack, … – just not it

So cleavage it is! .. and given it’s current state it is very much as Jerry Seinfeld says.

“Looking at cleavage is like looking at the sun. You can’t stare at it long, it’s too risky. You get a sense of it then you look away.”

Please keep in mind that this is very much a work in progress, but expect some updates in the near future.

I have posted the PhoneGap control sample app to: http://github.com/purplecabbage/cleavage

Documentation and such to follow later in the week, I hope, here is a quick getting started description.

In order to use this in your own ( pre-existing ) iPhone OS project, you will need to:

1. add all PhoneGap required frameworks to your project ( the sample project has them all )
2. add a reference to PhoneGapLib ( you will need the latest checked in version )
3. place your html/js/css in a www folder in the project and be sure it is packaged in the root of your app when built
4. include phonegap.js from PhoneGapLib, as it is not auto-copied over for you like it is in a typical phonegap iPhone app.
5. set linker flags for -all_load and -ObjC

Yesterday I made a quick update to a previous blog post. I will go into a little more depth here as some folks mis-understood that this was a new topic because it was part of the older post.

Recent changes to the Apple iPhone SDK developer license agreement have been a hot topic over the last week. There has been much speculation over how far reaching the 3.3.1 clause of the agreement is, not to mention the business strategy behind it. I will not join that conversation, but I will speak of what I have learned with regards to the impact on PhoneGap (iPhone/iPad).

Through email discussions with Apple, I specifically asked what, if any, impact did this have on present/future applications submitted to the App store that were built using PhoneGap. In no uncertain terms, my contacts at Apple have assured me that “PhoneGap is not in violation of the 3.3.1 clause of the license agreement.”

How this affects other tool-chains like Appcelerator, Flash CS5, Corona, MonoTouch, … I have absolutely no idea. All I can say is that PhoneGap is okay.

I will post updated information if I receive it, I have done a few other things to test the waters. Yesterday I submitted my iPhone PhoneGap Tutorial application to the App Store, I will post info here when/if it is approved ( although it may be rejecting for offering insufficient functionality, as it is a tutorial ).

The tutorial source code is available here: http://bit.ly/Jestitute

Okay, in your phonegap application in XCode, ( Without EVER having to touch the PhoneGapLib )

1) right click the plugins folder and select Add/NewFile/ObjectiveCClass
2) Call your new class : TestPlug
3) Paste the following code into the .m + .h files:

In your header file :


#import <Foundation/Foundation.h>
#import "PhoneGapCommand.h"
@interface TestPlug : PhoneGapCommand {
}
- (void)addThemUp:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
@end


… and in the .m file


#import "TestPlug.h"
@implementation TestPlug
- (void)addThemUp:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options
{
NSUInteger argc = [arguments count];
int total = 0;
for(int n = 0; n < argc; n++)
{
total += [[ arguments objectAtIndex:n] intValue];
}
NSString* retStr = [ NSString stringWithFormat:@"alert("%d");",total];
[ webView stringByEvaluatingJavaScriptFromString:retStr ];
}
@end


4) In your JS code, somewhere after deviceready, call your command like this.


PhoneGap.exec("TestPlug.addThemUp",1,2,3,4);

Build and run!

Note the structure of the PhoneGap.exec call
1) a command name : TestPlug
2) a method name : addThemUp
3) a variable length list of arguments

Next time, I’ll get into passing objects via the ‘options’ object.

If you have a compelling plug-in you want to share, you can fork my repo for plugins and send me a pull request :

http://github.com/purplecabbage/PhoneGap-Plugins

If your plugin makes sense on multiple devices, and it is implemented with standards in mind, it may end up in PhoneGapLib.

PhoneGap has been getting a lot of attention lately, and also a lot of questions on the mailing list about where to get started.
I recently built a small PhoneGap app for iPhone that helps to demonstrate PhoneGap functions.

The application is divided into multiple pages, and each page focuses on one area of functionality.
I have strived to keep each page dedicated to the functionality it presents, and present everything as simply as possible.
There are no dependencies on any other libraries, and the js / css for each page is contained directly there.

The Notifications page demonstrates key navigator.notifications functions.

• Custom Alerts – with custom title text, and button text.
• Display a loading screen for a fixed length of time
• Vibrate the device
• Show and hide the Activity Indicator ( the spinner at the top bar )

The Accelerometer page demonstrates navigator.accelerometer functions.

• Start + Stop the accelerometer update logic, and play with a bouncing ball.

( a shout out to Yohei for providing the initial code for this example. )

The Contacts page demonstrates navigator.contacts functions.

• Display the number of contacts
• Spawn the contact picker screen
• Renders a contact, and makes it clickable, to spawn the contact viewer.

The GeoLocation page demonstrates how to use navigator.geolocation

• Gets your current location
• Calls Twitter api using JSONP to get tweets within a mile of your location

( a shout out to Girlie Mac http://girliemac.com/blog/ this code was shamelessly borrowed )

Hopefully the other platformers will step up and publish / test on other devices. I have only worked on the iPhone branch so far.

I will be working on the Media api next to demonstrate how easy it is to play mp3s within PhoneGap, and I might even post some of my own music, we’ll see.

Get it while it’s hot! http://github.com/phonegap/phonegap-iphone

http://github.com/purplecabbage/Jestitute