Shazron's Cordova (aka PhoneGap) Blog

at Adobe Systems Inc.

Contributing to iPhone PhoneGap – Part 1

with 5 comments

[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:

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.


 @interface Preferences : PhoneGapCommand {

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


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.


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.


- (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

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.


Written by shazron

November 23, 2009 at 5:42 pm

Posted in phonegap

5 Responses

Subscribe to comments with RSS.

  1. Hi,

    This article gives lots of information.

    But could you please provide in details steps of the above. Seems I am missing some where which causing application not working.

    Need help. Thank you.



    October 22, 2010 at 3:40 pm

    • Which part is not working? Need details.


      October 28, 2010 at 9:44 pm

  2. Thanks Shazron.

    Now the app is working fine with some changes.



    October 28, 2010 at 9:45 pm

  3. Shazron,

    Your work is really fantastic. I learn a lot with your posts and apps.

    I tried using the writejavascript but it still fails when I call out of initial methods like this – (void) print: (NSMutableArray *) withDict arguments:
    (NSMutableDictionary *) options

    See my problem. Can you help me?

    André Rodrigues

    November 14, 2011 at 4:43 pm

    • Not enough information. Please continue posting on that thread.


      November 14, 2011 at 6:54 pm

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: