Contributing to iPhone PhoneGap – Part 1

[update: do not modify the core, instead create a plugin and add it into your app project. See PhoneGap Plugins for examples]

There has been a major re-factoring of the iPhone PhoneGap codebase, to better enable users to get a current version of PhoneGap to use in their projects without mucking about in the core PhoneGap code.

You can view the code here: http://github.com/phonegap/phonegap-iphone

The README has more details, and I will elaborate on it more here, especially on how contributors can add to the code.

PhoneGapLib/javascripts/core This is where you will add/modify your javascript code for PhoneGap core. You can add more javascript files here, but make sure you update the “PhoneGapLib/Makefile” file to include the newly added javascript file. For adding the file in the Makefile, the pattern should be obvious.

PhoneGapLib/Classes This is where you will add/modify your Objective-C code for PhoneGap core. You can add more Objective-C files here, but make sure you add it to the PhoneGapLib Xcode project also.

PhoneGapLib/javascripts/phonegap.js This is dynamically generated, and is generated whenever PhoneGapLib is built. You can update this file by running “make” in the PhoneGapLib folder, but generally it should be called in your application that includes PhoneGapLib (which the PhoneGap-based Application Xcode template does).

I will walk you through how to add a new command, by adding Application Preferences support. Download the files here.

Preferences.h

 @interface Preferences : PhoneGapCommand {
 }

- (void) boolForKey:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
 // other functions here

@end
 

Note that the class inherits from PhoneGapCommand. The class name you use here is important, since you will be referring to it in javascript.

To ‘expose’ a function to javascript, it must have the signature from the example ‘boolForKey’ method above (first argument is a NSMutableArray, the second argument is a NSMutableDictionary).

Let’s now look at the javascript command to access the function above.

preferences.js

function PreferencesManager() {
}

var g_Preferences = new PreferencesManager();
PreferencesManager.sharedPreferences = function() {
return g_Preferences;
}

PreferencesManager.prototype.boolForKey = function(key, callback) {
PhoneGap .exec("Preferences.boolForKey", key, GetFunctionName(callback));
}

The important line is the “PhoneGap.exec” line. The first argument to PhoneGap.exec is in the form of [className].[methodName] (refer to Preferences.h to see the corresponding function which should be obvious). The next arguments to PhoneGap.exec are two strings, which will be passed into the “boolForKey” method in the NSMutableArray which is the first argument. If an object (json object) is passed in as an argument to PhoneGap.exec, that data will be passed into the “boolForKey” method in the NSMutableDictionary which is the second argument.

Preferences.m

- (void) boolForKey:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options {
NSUInteger argc = [arguments count];
if (argc > 2) { // no key and/or callback - just return, no point in continuing
return;
}

NSString* key = [arguments objectAtIndex:0];
NSString* callback = [arguments objectAtIndex:1];
NSUserDefaults *userDefaults = [NSUserDefaults standardUserDefaults];

BOOL value = [userDefaults boolForKey:key];
NSString* retVal = value ? @"true" : @"false";
NSString* jsString = [[NSString alloc] initWithFormat:@"%@('%@', %@);", callback, key, retVal];
[webView stringByEvaluatingJavaScriptFromString:jsString];
[jsString release];
}

In the command itself, you can parse the arguments and options, and do whatever you need to do for your command. You can optionally write javascript back, using the method above, or the helper:

 [super writeJavascript:@"alert('foo')"] 

Don’t forget to add a Settings bundle file to your app as well.

Next: Adding your code to PhoneGapLib.

Create an iPhone PhoneGap application in 2 easy steps

Based on Jesse’s work on PhoneGapLib, I created a PhoneGapLib installer that will install the lib unto your computer, but most importantly, it will set a Xcode global variable to allow the PhoneGap Xcode template to work. The PhoneGapLib installer will also install a PhoneGap Xcode template.

Creating a PhoneGap iPhone project has never been easier. This way also, if PhoneGap core is updated it will not affect your code. The main parts of the code should already be checked-in (see Jesse’s post for the url). This is a work in progress. [Updated: Download a preview version]

To download the code and build the installer, go to http://github.com/phonegap/phonegap-iphone and read the README.md for build instructions. No binaries are provided at this time.

See screencast below:

Microsoft Gestalt TextMate Bundles

I recently completed a project for Gestalt – Microsoft’s library that allows you to write Ruby, Python & XAML code in your (X)HTML pages.

The project consisted of writing two TextMate bundles to enable developers to have syntax highlighting and code completion for Ruby, Python and XAML in their Gestalt pages (which are regular XHTML). XAML is a declarative syntax (via XML) to enable vector graphics in the browser (rendered using Silverlight). Silverlight is used to interpret the Ruby and Python code also.

To download the TextMate bundles, go to:
http://visitmix.com/labs/gestalt/downloads/

Apple's WWDC 2009 – See you there!

I will be representing Nitobi at Apple’s WWDC 2009 in San Francisco, and will be in the various after-conference parties about town. I will be in SF from Sunday June 7th to Friday afternoon June 12th.

If you’d like to meet up and chat, send me an e-mail at shazron@nitobi.com or ping me on Twitter. See you there!

The State of PhoneGap with Windows Mobile

Well there is no state really, except for the proof of concept currently (by PhoneGap contributor Jose Noheda). I was re-factoring the PoC code, and getting everything working with the PhoneGap Javascript common code. In a nutshell, PhoneGap WinMo cannot use the existing PhoneGap js [1], as js support in the IE control in WinMo is too primitive. The current IE in WinMo is based on desktop IE 4 (released in 1997) and only supports JScript 3/Javascript 1.3.

So where does this leave PhoneGap WinMo? These are the ways we can proceed:

1. Have a totally separate Js codebase, based on JScript 3, for WinMo. Con: Maintenance nightmare?
2. Upgrade to IE Mobile 6. This discussion has its own section, below.
3. Use WebKit with Qt [5]. Pro: We can probably use Qt Webkit in Nokia phones (soon, not supported yet), because well, Nokia owns Qt. Con: Using Qt adds a 10MB overhead, minimum.
4. Use our own WebKit control. Con: I don’t know how long this effort will take, and it is the riskiest.

Internet Explorer Mobile 6

IE Mobile 6 is based on desktop IE 6 (which was released in 2001) but with the IE 8 Javascript engine [2]. However, only newer (unreleased as of yet) phones will get this version, according to Microsoft [3]. Although there are development emulator images available, they are no substitute for testing on a device.

Even if we somehow get IE Mobile 6 on existing phones (with unofficial ROMs, eg through xda forums[6]), .NET code cannot take advantage of this, because Microsoft does not want to break existing compatibility with existing code that uses hosted controls [4].

Footnotes:

[1] Sample PhoneGap Javascript code that fails under IE Mobile 4 JScript http://pastie.org/485649

[2] IE Mobile 6 release blog post http://blogs.msdn.com/windowsmobile/archive/2008/11/11/internet-explorer-mobile-6.aspx

[3] IE Mobile 6 will not be available for current phones http://blogs.msdn.com/windowsmobile/archive/2008/11/11/internet-explorer-mobile-6.aspx#9063740 [All comments were deleted after the fact by MS]

[4] IE Mobile 6 will not be available in hosted controls (ie .NET WebBrowser component) http://blogs.msdn.com/windowsmobile/archive/2008/11/11/internet-explorer-mobile-6.aspx#9064039[All comments were deleted after the fact by MS]

[5] Qt toolkit http://www.qtsoftware.com/

[6] XDA Developers forum http://forum.xda-developers.com

Hello world!

Hey, I’m the newest part of the Nitobi team. This blog proves it Nothing to write about right now, but in an upcoming post I will write about my travails with Windows Mobile …