Build process experiments with PhoneGap

I’ve made some quick updates on the train this morning, and ended up creating a Bourne shell script in the iPhone directory of PhoneGap for renaming a brand-new PhoneGap fork to whatever your project is called. This also works with the previous changes I made to my buildprocess branch, meaning that when you’re done, you shouldn’t have any references to PhoneGap in your code at all. It also makes developing quite a lot easier, since renaming my XCode project file by hand is cumbersome, and needs to be done every time I start a new project.

Continue reading “Build process experiments with PhoneGap”

PhoneGap gets a fancy new demo

The PhoneGap demo is really starting to grow beyond the capacity of a single screen since tons of new features are being added all the time.  It’s even showing a few examples of the tab and navigation bar features, but they didn’t really do anything beyond just throwing out alerts and log statements.  I decided to change that to show just what’s possible with a PhoneGap app.

(Forgive me for the ugliness of the video…this is my first upload to YouTube, so I had assumed I could resize the embedded viewer to fit the aspect ratio of the original).

I’m pretty excited about it.  Not only does it give developers a starting place for developing apps, but it allows us to improve the demos to give the user a better experience.  I’d like to show a Canvas graph of the accelerometer values, or even show a rolling ball in a box to see how the accelerometer can influence JavaScript.

New PhoneGap feature: ActionSheet support

A while back David Roe had sent me a patch for an implementation of the ActionSheet control for PhoneGap. He was using it in an application of his, and probably due to my plea for patches from the PhoneGap community at large, he submitted this little tid-bit to me. Since I’ve been making some pretty big strides toward implementing a unified callback and event dispatch mechanism within PhoneGap, I refactored a bit of it, and created a generic Dialog class for PhoneGap.

Currently only button dialogs are supported, but in the future I’d like to create a variety of dialogs that PhoneGap application developers can use; date pickers, scroll picker widgets, and so forth. The API is as simple as I could make it, while still keeping in mind that other platforms may not have a native control to accomplish these features.

Basically I was thinking “What would I want to put in an action sheet”, and I came up with:

  1. A list of buttons, maybe with different colours
  2. A date / time picker, maybe with a different start date
  3. A scroll-wheely value selector
  4. ….

Here’s the desired API I came up with for a very complex usage:

{ label: “First button”, type: “default”, onClick: function() { … } },
{ label: “Second button’, type: “cancel”, onClick: function() { … } }

which would result in the following GAP command:

gap://Dialog.openButtonDialog/First button/Second button?type_0=default&type_1=cancel&onclick_0=…

and so on. With the event callback system I built, the onclick handlers will be given their own callback ID if they’ve been specified. Additionally, the following syntax is supported as well, for more simple uses:

“First button”,
“Second button”,
{ onClick: function(index, label) { … } }

so you just give it a list of buttons, all shown as a default type, and the function would be called no matter what button was pressed.

This second form is necessary as you’d probably use it for the other types of action sheets:

new Date(‘2009-02-14’),
{ onClick: function(newDate) { … } }
‘Value 1’,

‘Value 2’,
‘Value 3’,
{ onClick: function(value) { … } }

Those most recent examples aren’t implemented yet, but it shows how this particular class can be extended in the future. And they’re all potentially supported on other platforms as well.

Does all this sound reasonable? Please leave comments if you have any thoughts on the matter.

Check out the documentation of the Objective-C Dialog implementation, and the JavaScript Dialog interface to it. If you want to play with this before I push it into the official branch, you can try it in my experimental UIControls branch.

Minor PhoneGap Alert updates

Last night, and on my commute in to work this morning, I made some updates to my UIControls branch on Github, largely around adding callback and event support to the Alert notification code.

I’ve been working on providing more feedback into JavaScript from the commands run inside of Objective-C.  So far PhoneGap has been largely one-way, you push actions into PhoneGap and maybe you get some sort of response out in some general sort of way, but most of it has involved polling mechanisms.  Well the DOM and JavaScript in general has a native facility for dispatching ad-hoc events.  And it’s super easy to call from Objective-C, if only a little bit verbose:
[webView stringByEvaluatingJavaScriptFromString:
@”(function(){ “
“var e = document.createEvent(‘Events’); “
“e.initEvent(‘alertClosed’, ‘false’, ‘false’); “
“e.buttonIndex = %d; “
“document.dispatchEvent(e); “
It looks a little complicated, but it really isn’t.  It’s calling some code in an anonymous function closure so this doesn’t leak any references or variables into the global scope, creates a DOM event, sets it with a custom event name, adds some arbitrary properties to it, and dispatches it against the document element.
This same pattern applies everywhere some event occurs, and something in the JavaScript side of the gap:// barrier might be interested in it.  Listening to this event is as simple as doing:
document.addEventListener(‘alertClosed’, function(e) {
debug.log(“Alert box with button ” + e.buttonIndex);
}, false);
Pretty simple, and super flexible.  If you’re interested in an event, you bind an event listener to it.  If you’re not, you simply ignore it.  I’m pretty excited about this design pattern since it reduces the complexity of having to loop and wait for something that might never happen.
Update: Oh, I almost forgot.  The main reason for doing all this is I added the capability to add a second button to the Alert popup.  So you can do “OK / Cancel”, or whatever else you want.  But doing so necessitated adding callback support so you could tell not only when the user closed the alert, but so you could tell which button they pressed.

Open letter to Apple iPhone Developer Support

I’m a big fan of all things Apple, and as you can tell from my past blog posts I’m a big fan of iPhone development. I’ve even dusted off my aging C skills, and have learned to love Objective-C. The one thing I haven’t learned to love, like all other iPhone app developers, is their application release process, and the seemingly arbitrary app store acceptance department.

Don’t get me wrong, I think how Apple fiercely guards the App Store to prevent bad, buggy, or offensive material from getting on there is a great thing. Some of my mother-in-law’s students in the class she works in have iPhones or iPod Touches, and these little 10-year-olds love the little apps I’ve put out. They’re fun, light-hearted, and they get a lot of enjoyment out of these and other apps. It’s reassuring to know that if I install an app, it won’t crash my phone (too badly) or that a child won’t be offended by them (too much).

However, the level of detail they give in their rejections seem both arbitrary and unnecessary. You develop an app and have to throw it over the fence to Apple, after which you wait with no level of detail as to the status, or success, or any sense of progress through whatever queue they have. Finally, you more often than not get a big fat rejection letter that gives you no detail as to why your app didn’t meet their secret criteria.

In my experience so far, this has actually been a virtue. My apps actually did have minor race conditions, or problems on specific platform versions. So, fair enough, I fix my changes and submit them in. But recently, the framework I work with and have been helping develop seems to be under fire from Apple for no apparent reason. And it’s the contradictory nature of their message that is what gets under my skin.

In this long thread on the PhoneGap mailing list, a number of developers writing their applications under PhoneGap have been given rejection letters saying something like:

Upon review of your application, cannot be posted to the
App Store due to the usage of private API. Usage of such non-public
API, as outlined in the iPhone SDK Agreement section 3.3.2 is

” An Application may not itself install or launch other executable
code by any means, including without limitation through use of a plug-
in architecture, calling other frameworks, other APIs or otherwise.
No interpreted code may be downloaded and used in an Application
except for code that is interpreted and run by Apple’s Published APIs
and built-in interpreter(s).

The PhoneGap API implemented in your application is an external

For those new to PhoneGap, it’s a project that gives you an XCode project directory with Obj-C classes pre-made that allow you to develop iPhone apps in HTML / JavaScript. It wraps up several of the iPhone’s native controls and exposes those capabilities to JavaScript. In this way, an application developer could write their app in a hybrid of native Objective-C code and the iPhone’s own native browser control, the UIWebView.

It seems though that Apple constitues the use of their own controls as a 3rd-party library. Apple’s own developer documentation includes code sample projects, much like PhoneGap’s, intended to get a developer started on using their SDK. Is it incorrect to assume that others can do the same?

Additionally, there are 3rd-party companies such as AdMob, Medialets, and a number of others that provide ads, application tracking, and other resources to iPhone developers. Their code is given to you as pre-compiled libraries, that are most certainly not included on the iPhone when you pull it out of its shrink-wrap. So how is it that all these apps are released to the App Store with these 3rd-party libraries linked in, and an app framework whose source code is freely available and uses officially documented features can’t be?

I decided to put an end to the speculation, and wrote a letter to Apple’s developer support on this matter. I’ll give it a chance to percolate through their support department, and if I don’t hear an answer back via email, I plan to call their support department until I can get an answer.

For future reference, and in the interests of keeping the discussion open, here’s a copy of the letter I sent in to Apple.

From: Michael Nachbaur
Date: May 17, 2009 6:04:28 PM PDT (CA)
Subject: Library classification clarification

Hello, I’m an iPhone software developer, and one of the core developers of the PhoneGap project. A number of users of PhoneGap – a set of Objective-C classes aimed at leveraging the UIWebView to access iPhone-supported hardware features – have reported that their apps have been rejected from the App Store because they supposedly use a “3rd-Party Library”. I wanted to get some clarification about this, as this is not only untrue, it is completely at odds with the goals of our project.

PhoneGap only uses officially-supported features of the iPhone, as documented within XCode’s iPhone SDK documentation. We even make sure that we don’t even use deprecated features of the iPhone, as we want to ensure 100% compatibility. All the software we use is exposed natively by the iPhone, and is in use in many other apps on the App Store.

So I wanted to get an official clarification from Apple as to why these apps are being rejected, and what, if anything, we as the maintainers and developers of the PhoneGap project can do to rectify the situation. We are trying to empower developers with quality starting-blocks for developing their own applications, much as the Apple sample applications do.

So please, if there’s anything we’re doing wrong, we would more than happily change our code to accommodate Apple’s policies. As far as we can tell, we support Apple’s licenses even better than other apps on the App Store, because we don’t import 3rd-party libraries such as AdMob, Medialets, or any of the other ad and tracking libraries that are obviously featured on almost every app in the App Store. And these are quite plainly 3rd-party libraries, and as such should they not be even more restricted than we are?

As a community, of both software developers and of business-people, we are very anxious to hear back from you, and would like to discuss this with someone at Apple to get an official answer, instead of the conversation being one-sided and filled with speculation.

Thank you for your time, and I look forward to hearing back from someone soon.

What are your thoughts on the matter? Can anyone reading this find some reason why Apple would target PhoneGap?

Update: I got an update on this problem from Steve, one of the app reviewers, over at Apple.

So much to do, so little time

I think work wrecked my brain a bit today. I have so many ideas running through my head, and just not enough time to catch up to them all. It happens to all of us from time to time, but the thing is I have so much fun with work, that it’s hard to moderate myself. I think I’m going to head home, listen to some Bob Marley, and when I meet up with my wife and her parents at the pub, I’m going to watch the hockey game, drink some beer, and enjoy my evening without technology.

That being said, I’ve recently made some great updates to PhoneGap, and have added some docs. Check out the generated JavaScript documentation and iPhone documentation from my personal branch at Github. I’m sure we’ll get the docs pushed up to the main PhoneGap website soon.

PhoneGap UIControls ready to go

I’ve merged the results of my UIControls branch on github into my master branch. I think my little experiment went well, and I’d love to get feedback from people on how this new API works for you. I still have some great plans for it, but before I get ahead of myself, let me cover what I’ve done:

• Refactored the command call API to allow for a richer set of arguments to PhoneGap commands
• Moved some commands around to more appropriate classes (e.g. Alert and Vibrate both moved to Notifications)
• Reorganized the XCode project so commands are clearly separated from PhoneGap infrastructure
• Renamed the Settings.plist PhoneGap config file to PhoneGap.plist, and created a new Settings.plist file that contains custom application-specific configuration.
• Made all PhoneGap commands inherit from a common base-class that auto-loads its own Dictionary of configuration from the main PhoneGap.plist file.
• Added UIControls command class that exposes tab bars and toolbars to JavaScript.
• Updated the demo to show off tabs and toolbars

All that looks like a big change, but almost all of it was infrastructure changes that were necessary to get UIControls to work. Previously, all PhoneGap commands were class method calls, meaning it was very difficult to maintain state between command calls. Now that commands are actually called on an instance of a given command class, it’s easier to maintain state. So when a tab bar is created, multiple calls can be made, each to construct different aspects of the UI. Without all this, the following example would have been much more complicated:

uicontrols.createTabBarItem(“toprated”, “Top Rated”, “tabButton:TopRated”);
uicontrols.createTabBarItem(“recents”, “Recents”, “tabButton:Recents”);
uicontrols.createTabBarItem(“more”, “More”, “tabButton:More”);
uicontrols.showTabBarItems(“toprated”, “recents”, “history”, “more”);

The changes to the PhoneGap configuration were necessary because now, when a PhoneGapCommand subclass is constructed, it will look in the PhoneGap.plist configuration file to see if there’s anything pertaining to it. So if there’s a key in the dictionary with the same name as the class being constructed, it will use that as a local configuration dictionary influencing just that one class. That way, if you don’t use a feature of PhoneGap, or you have to configure a lot of options for a single type of command, these options won’t be cluttered alongside the standard global PhoneGap settings.

I created Settings.plist because of experiences I had in an application I’ve been creating in order to test my new UIControls branch changes. I found that I wanted to set compile-time options (for instance a “lite_mode” boolean) that influenced the way my app runs, without having to change HTML or JavaScript code every time. So instead what I have is a configuration plist file that is used exclusively in JavaScript for my application. I’ve added the excellent SB-JSON framework in to the PhoneGap project, and use that to pass these settings into the JavaScript application at start-up time. So all you have to do is read Settings.lite_mode, for instance, in order to read properties set in your plist file.

Oh, and finally, I’ve moved the JavaScript documentation to javascript/docs, since they were practically impossible for new users to find in the past. I’ve been working on creating DoxyGen docs of the PhoneGap code for use in XCode’s documentation browser, but I haven’t gotten far enough there to actually check anything in besides comments. I found instructions on how to generate XCode docsets from DoxyGen, but I haven’t gotten it working just yet.

So please, try out my PhoneGap updates and let me know what you think of it. I think the integration of the JSON framework will make things like Contacts much simpler to implement.

Before I go though, I want to give a little “wish list” of features I’m planning on adding in the near future. I’ll get to them whenever I can, since my own app development takes priority of course.

• Toolbar buttons
• Tabbar show/hide animations
• File support (read / write local files)
• Camera and photo library support (POST to a server, save to a local file, etc)
• Native “Flip / Slide” transitions (no more having to mimic them in CSS)
• 3rd party API integration, like AdMob and Medialets (I already have both of these done, but I’m in discussions with both companies to determine if the terms of their license allows me to redistribute it)