I know HTML. Its on my CV. Expert level. I also know CSS and a whole bunch of JavaScript. I can even do TDD with JavaScript.

And on the iPhone there is this nifty object called UIWebView. Otherwise known as WebKit. Otherwise known as an embedded browser in your iPhone app.

And if you want a sexily awesome looking UI view, like the Today view of the Surf Report app (see right or free on AppStore) that was released on the AppStore recently, then the WebKit is just the best thing since the electric bread slicer for speed of development.

Holy grail of iPhone development?

Well, that’s what we thought. When I chatted with Dan Grigsby last week I mentioned there were good and bad things about the WebKit within an iPhone app.

This article is about good and bad things. The pros and cons. How we managed the integration of the two code-bases. And the answer to the big question: Would we do it again?

Its probably wonderfully useful stuff to know.

Negatives

So first the downsides. It would be remiss of me to fill you full of unbounded promises of easy non-Objective-C victories in your iPhone dev, and not tone them down with a full bucket of wet reality.

Its slow. When the WebKit is first loaded into memory, and we try to do this behind the scenes as soon as we get control of our app from the OS, it can take a good few seconds for your WebKit object to be available. You get notified of its readiness for action via the delegate:

- (void)webViewDidFinishLoad:(UIWebView *)webView

Its slow. You’re running an interpreter (JavaScript runtime) on top of a device with a small CPU and small memory. Go figure.

This reminds me of the fabulous “two minor drawbacks” scene from the 80s British sci-fi comedy Red Dwarf:

CAT: Why don't we drop the defensive shields?
KRYTEN: A superlative suggestion, sir, with just two minor flaws.
  One, we don't have any defensive shields, and
  two, we don't have any defensive shields. Now I realise that,
  technically speaking, that's only one flaw but I thought
  it was such a big one it was worth mentioning twice.

The JavaScript bridge does not appear to block the main thread. This is a good/bad thing. You can invoke JavaScript code within the WebKit via your native Objective-C code.

[webview stringByEvaluatingJavaScriptFromString:@"loadData({some: 'data'})"];

It seems to return control back to your Objective-C code before it has finished executing, so you may need to poll the JavaScript runtime with `isFinished();` calls if you need to know when its complete.

Annoyingly, the Apple documentation for this method suggests otherwise:

JavaScript execution time is limited to 5 seconds for each top-level entry point. If your script executes for more than 5 seconds, Safari stops executing the script. This is likely to occur at a random place in your code, so unintended consequences may result. This limit is imposed because JavaScript execution may cause the main thread to block, so when scripts are running, the user is not able to interact with the webpage.

Quirky.

The JavaScript bridge is one directional. From Objective-C/UIKit you can invoke JavaScript upon the WebKit and henceforth do wonderful things (as per example above).

From JavaScript you have no native nor nice way to invoke methods on Objective-C objects, like you can in the Cocoa implementation of embedded WebKits. What you can do is use custom HTTP protocols, such as surfreport://, to give the OS a way for the webkit to communicate with your app.

We used this for ‘Related Photos’ buttons on some news and athlete’s pages. When you click a button in the webkit, it attempts to redirect to a surfreport:// url. The Objective-C code (your `UIApplicationDelegate`) is notified of this, hides the webkit, and displays the related photos using native UI elements. But we could do anything. Your `UIApplicationDelegate` needs to implement the follow method to receive these requests:

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url

Alternately, you could use JavaScript to invoke this url, possible, via an Ajax call. Haven’t tried it. Might work. Either way, its a dirty hack, and a very annoying situation given that in Cocoa development there is a beautiful two-way bridge. I want that.

Multiple languages in one project. Whilst we mainly just wanted to take a static HTML file, and dynamically update various elements with application data (e.g. the surf and weather conditions in the example above), we needed to do that via JavaScript.

We came up with a consistent API loadData(json) for all pages, as discussed below; yet when something displayed incorrectly we now had an extra possible point of failure: JavaScript, Objective-C, and the original web service data source (e.g. the Surfline data for live updates).

To help isolate issues, we used JavaScript unit testing and a layer of “fixtures” or samples of JSON that might be sent from Objective-C to JavaScript. The tests passed against the fixtures; so if a QA error appeared in the app, we first checked the JSON being sent against the fixtures schema to isolate whether it was a JavaScript error or a data format error. It happened sufficiently often that its worth raising here.

WebKit for rapid prototyping

Nonetheless, the WebKit exists and it is awesome at rendering HTML and CSS, with access to the powerful CSS3 transformations and webkit-specific bonus features.

It is highly likely that your designer can make something beautiful looking in Photoshop and cut it up into HTML + CSS. Comparatively, its highly unlikely they can cut it up into native Objective-C code.

So in the initial phases of application development/prototyping, the WebKit is a sweet option to give the designer on your team direct, immediate access to building the app. If performance is an issue, you later replace it with native UI elements.

Code layout and samples

In our Xcode project, the structure we use for including HTML and associated assets into our apps is:

Classes/           - normal Objective-C .m/.h files
Html/src           - HTML, CSS, and JavaScript files including libraries like jQuery
Html/test          - JavaScript tests
Html/test/fixtures - expected JSON formats to be sent from Objective-C to loadData methods

These aren’t Xcode Groups, rather normal filesystem folders. In the Xcode project, the Html/test files are not included nor bundled with the app. The files in Html/src are included in the “Copy Bundle Resources” of the Target (see image) and also linked into the project via a sub-group of “Resources”, so they can be easily accessed within the project.

But when I did the HTML/JavaScript development I worked from the command-line and TextMate, and lived entirely inside the Html/ folder.

For each static HTML page, such as the ‘Today’ view above, there will probably be the following files:

Html/src/today.html
Html/src/today.css
Html/src/today.js
Html/src/jquery.min.js
Html/test/unit/today_test.html

The WebKit will display today.html, which uses normal <link>/<script> to pull in the .css and .js assets. You can quickly see what the page will look like, even before integration into your app, by loading it into the iPhone Simulator (launch the simulator and drag the file in), or even Safari 3.

We settled on a standard API for the primary call from Objective-C into JavaScript: loadData(json). Bare-bones, this method starts off looking like:

// This function is called from Objective-C-land to apply
// the surf information to the HTML template
// +data+ is a hash of key -> value
function loadData(data) {
    $('.data').html('N/A');
    $('img.image_data').removeAttr('src');

    // Assume that any data key can be copied into any HTML element with the same ID
    for (var key in data) {
        var value = data[key];
        var value_exists = fieldExists(value);
        var data_value = value_exists ? value : 'N/A';
        var img_src_value = value_exists ? value : 'unknown';
        $('#' + key).
            filter('.data').html(data_value).end().
            filter('.image_data').attr('src', key + '_' + img_src_value + '.png');
    };
}

What it does is take a data hash like { surf_height_amount: '2-3', surf_height_unit: 'ft' } and HTML like:

<div id="surf_size">
  <span class="data" id="surf_size_amount"></span>
  <span class="data" id="surf_size_unit"></span>
</div>

And the loadData method updates it to:

<div id="surf_size">
  <span class="data" id="surf_size_amount">2-3</span>
  <span class="data" id="surf_size_unit">ft</span>
</div>

So we can build arbitrarily complex HTML templates. By allocating meaningful element IDs (surf_height_amount) and tagging the template elements with class="data" we have a simple mechanism for Objective-C to update the HTML. As the template gets more complex, then so too does the loadData method.

Would we do it again?

Yes.

The WebKit isn’t the holy grail for non-Objective-C developers, but if your grand-poobar level skills are in JavaScript and HTML, and your Objective-C/iPhone skills are still catching up, then its a wonderful prototyping platform. Especially for static, complicated displays of data. Especially if that data includes HTML content from an external feed which needs to be rendered.

For Oakley’s Surf Report app, Anthony is toying with replacing some of the WebKit usage with native UI elements (normal UITableView with custom UITableViewCells) so that we can get back those precious seconds and give them to the user as a Christmas present.

Related posts:

1. iPhone dev podcast about fmdb-migration-manager and rbiphonetest Radio is where ugly people go. Podcasts is where ugly,...
2. Unit Testing iPhone apps with Ruby: rbiphonetest Everything to love about Ruby: the concise, powerful language;...
3. Prototype: “element-id”.$() instead of $(‘element-id’) The Prototype library gives us the $() operation for converting...

1. X = Dr Nic
2. Y = iPhone development
3. Z = Ruby

From the Mobile Orchard news desk:

Dr. Nic talks about his migration manager for updating SQLite iPhone databases, trying to get Ruby onto an iPhone, using Ruby to unit-test Objective-C iPhone code, his company Mocra, and the Mobile Orchard Podcast’s lavish recording studios.

Dan Grigsby is the interviewer and post-production guy for the interview, and so it is entirely his handy work that it seems like I’m the only one talking for 15 minutes. The original interview took 4 hours and it was mostly him talking. He’s quite a chatterbox. I barely got a word in edgewise. [1]

Dan also created this list of “things we talked about”:

1. 0:00: Migrations for SQLite
2. 5:18: Getting Ruby onto an iPhone
3. 5:59: Nu – Lisp-based language that sits atop Obj-C and would work on the iPhone
4. 7:37: Unit testing Obj-C from Ruby
5. 8:12: Webkit UIs
6. 12:31: Mocra / “Used my blog for evil”

Go to Mobile Orchard (or Mobile Awkward it is accidently called at the end of the interview) to cop a listen.

[1] This paragraph starts well and ends with blatant falsehoods.

Related posts:

1. To WebKit or not to WebKit within your iPhone app? I know HTML. Its on my CV. Expert level....
2. Unit Testing iPhone apps with Ruby: rbiphonetest Everything to love about Ruby: the concise, powerful language;...

Everything to love about Ruby: the concise, powerful language; the sexy testing frameworks; and finally, the people.

Everything to love about Objective-C: hmmm; well…; and finally, its the only high-level language you can use to write iPhone apps.

On iPhone 2.0, to arrive on the 11th of July, you cannot run RubyCocoa. But you can run it on your Mac, so let’s use it to unit test your Objective-C classes. This tutorial shows you how to get started using a new project rbiphonetest [GitHub | Lighthouse | Google Group]

If you followed some of my recent tweets, this project was previously called “iphoneruby”. And alas, the screencast also calls it “iphoneruby” but that was a crap name. People thought it was a way to run Ruby on the iphone. I can’t do that yet. So, a far better name is ‘rbiphonetest’. [track on summize]

Even if you’ve never touched Objective-C, Cocoa, the iPhone SDK, nor RubyCocoa I recommend watching the video anyway. It should give you hope that if you make the transition to iPhone development you don’t have to go alone without Ruby: your trusty swiss army knife of language/libraries/tools.

The screencast is also available in high-def video (55Mb QuickTime)

Unit Testing iPhone apps using Ruby from Dr Nic on Vimeo.

Installation and Usage

To summarize the video, but change ‘iphoneruby’ to ‘rbiphonetest’, you install the framework via RubyGems:

sudo gem install rbiphonetest

Then change to your project’s folder and install the test framework:

rbiphonetest .

Finally, for each generic, non-UIKit-framework-using class you want to test:

script/generate model WidgetModel

Then write your tests in test/test_widget_model.rb

Supported Cocoa & iPhone frameworks

The mysterious, magical premise upon which rbiphonetest depends is possibly erroneous: that your Objective-C class can be compiled and tested against your OS X/Intel frameworks, and if your tests pass you assume you can then compile and include your class with the the iPhone/ARM frameworks.

I’m willing to go with this assumption until its proven dangerously flawed by some angry 20-year veteran of NextStep/Cocoa/iPhone. But really, how different could NSString be on the iPhone versus your Mac?

Fortunately there is one way to check for significant differences between your available Mac-based frameworks, such as Cocoa, and the iPhone-based frameworks, such as UIKit. We need to compare the framework names, header files and method signatures.

So for example, you cannot currently unit test any class that depends on/includes the UIKit framework. Why? It doesn’t exist on your Mac, so the Mac/Intel compiler cannot link it in. We’re compiling and running our tests with RubyCocoa, which itself is built against the Mac/Intel frameworks, not the iPhone frameworks. Hell, Laurent doesn’t even own an iPhone [Laurent is the Apple-employee maintainer of RubyCocoa and the newer MacRuby]

Similarly, its no use including/linking the Cocoa framework into your Objective-C class. Why? It doesn’t exist on the iPhone. It has its own UI frameworks, collectively called ‘UIKit’.

So for the moment we cannot test UI-related, iPhone-API-specific code. But we can test generic Objective-C. That’s better than a kick in the teeth. Surely. I mean, in the teeth… that’d friggin’ hurt.

“Fair enough Dr Nic, so which frameworks can my code use and yet still unit test it with your oh-so-special test library thingy?” Keep your pants on, I’m getting there. [ref]

To the best of my ability, I’ve compared the two sets of frameworks and listed the available Frameworks that are available on both the iPhone and your Mac. There are about a dozen. The most important is called ‘Foundation’. It holds gold nuggets like ‘NSString’.

The list of platform differences is on the wiki as a reference.

Note, this list doesn’t guarantee that any two framework classes – the iPhone and matching Mac framework – will behave the same. This list is compiled by finding the set of Frameworks with the same name on both platforms, e.g. Foundation.

Then it compares the set of public header files (Foundation.framework/Headers/*.h files) This comparison is by method signature. It pulls all lines from each header that start with + or – (+ is a class method and – is an instance method in Objective-C) and compares the two lists. If there is a single difference in the method signatures of the header files in the two platforms it is marked on the wiki page. You’ll need to look at the two header files yourself to see the differences. Some header files are ugly. C-based anything starts ugly and goes down from there, I think.

Python testing of iPhone Objective-C?

In the Python world there is PyObjC, a bridge-based twin to RubyCocoa. If you are a Python developer you could easily port this project to use PyObjC I would think. Ping me if you are attempting this and need any help.

Summary

I think this project can give Ruby developers a happy place to work from as they write their Objective-C/iPhone code. You still need to wire up your UI views and controller classes manually, but if you push all the “oooh that code really needs some tests” classes away from the UI-dependent frameworks then you can hook it up to rbiphonetest and write your tests in Ruby.

Currently the generator creates test/unit test stubs. I personally then add the Shoulda gem into my test_helper.rb for my apps. If an rspec and/or test/spec developer can help with adding support to the generators I’m certain the large rspec user-base would be happy campers.

Similarly, someone might like to investigate using MacRuby to run the tests instead of RubyCocoa. Fast tests vs slow tests. You choose.

What the?

Sometimes I re-read what I’ve written and notice things that don’t seem to make sense, but are in my vocabulary nonetheless. Yep, the things you learn living in Australia.

“Keep your pants on” – this seems to imply that until I mentioned otherwise you were about to take your pants off. Hardly relevant at any stage during this article, we’d both agree. Most code-based blog articles are “pants on”. This phrase means “don’t get upset”. You can try to figure out how you go from “don’t get upset” to “keep your pants on”. I have no idea.

Related posts:

1. Validate and Save your Ruby in TextMate – with secret Rubinus superpowers In some TextMate bundles, if you save a file it...
2. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...
3. Future proofing your Ruby code. Ruby 1.9.1 is coming. Bugger. I’m a Ruby monogamist. I use the Ruby...