Volume Number: 22 (2006)
Issue Number: 6
Column Tag: Web 2.0

"Web 2.0" on the Desktop

Replacing AppKit with the New Web Fu

by Troy Dawson

The Hybrid JavaScript Application

"You can also access JavaScript from Objective-C and vice versa." This statement can be found casually tacked onto the end of the Apple Developer Connection introduction to the WebKit framework. But given this capability, and a place to stand, it is quite possible to move the world...by layering application UI over WebKit's DHTML support instead, of over AppKit.

The benefits of this hybrid approach can include:

• Writing UI code in the lighter-weight JavaScript environment

• Using CSS's "look and feel" specifications to produce static layouts and a dynamic user experience

• Significant (if not complete) code commonality ("write once -- run anywhere") with Windows and Linux personal computers, and potentially any device with a standards-compliant web browser

• Simplified communication with the rest of the world via asynchronous HTTP data interchange

• x86 binaries? Endian jive? JavaScript is interpreted (and so high-level integers can live as strings)

• The ability to embed a web application project into a native OS X test-harness for more convenient bring-up and development

This article will survey the route of development that I took in authoring such a hybrid WebKit-based application.

What is WebKit?

WebKit is an Apple system framework that renders web content into a window. Introduced with Mac OS X 10.3, and supported back to 10.2.x, it serves as the core of Apple's "Safari" web browser. In mid-2005, WebKit became an open source framework (part of the Darwin project), and is now hosted at http://webkit.opendarwin.org/. Its HTML renderer and JavaScript scripting engine are the key elements needed for embedding the modern W3C DOM platform into a desktop application.

OK, What Is Web 2.0?

Tim O'Reilly has answered this question with, "Web 2.0 doesn't have a hard boundary, but rather, a gravitational core" of an evolved web-as-platform metaphor (O'Reilly, 2005). Buzzword or not, 2005 was the year of "Web 2.0" in the computer world. Great amounts of hype and capital investment were generated by the slick user experiences provided by Gmail, Google Maps, Flickr, and others. These applications are known as Rich Internet Applications, and tend to share the following attributes:

• Lightweight, "disposable" client application, often just a bog-standard browser

• Server-side data management, loosely-coupled via HTTP to a slick front-end client UI

• Open standards: Dynamic HTML ("DHTML"), XML, RSS

• OS-Agnostic: Windows, OS X, Linux can be equal citizens

• Software releases in perpetual beta, with code revs "going live" nightly

But for the purposes of this article, "Web 2.0" will mean the DHTML platform used to make the application's UI a compelling user experience, and, optionally, HTTP data interchange with remote servers.

Replace AppKit With This? What For?

In times past, AppKit was state-of-the-art and HTML was rather lame, as far as the user experience went. These days, however, it can be argued that the capabilities of modern HTML renderers, implementing the powerful combination of JavaScript, the W3C DOM, and CSS, have surpassed poor, neglected AppKit in some important areas. I think even some Apple engineers would agree, as evidenced by Dashboard, one of 10.4's centerpiece features, requiring DHTML for its "widgets", and also by the scarcity of the AppKit "look and feel" in Apple's own iTunes Music Store. One may also see some influence of DHTML development patterns in Microsoft's next-generation "Avalon" / WPF lightweight desktop client environment coming soon with Windows Vista.

While browser-hosted DHTML functionality can be implemented in a wide range of environments, for example, Netscape's XUL, Macromedia Flex / Flash, Laszlo, Python, and Ruby, two important benefits of going with WebKit are: 1) simplified user installs -- it is possible to write client UI code that looks and runs identically (without any plug-ins or other end-user hassle) while either embedded in a WebKit app, or rendered by today's web browsers; and 2) the clean, two-way bridging that WebKit provides between the separate JavaScript and Objective-C environments of a hybrid OS X / WebKit application.

Of course, moving of AppKit means that one loses some amount of GUI goodness: many of the "Aqua" buttons, sliders, and so on, that we have come to know and love. CSS behaviors, form input elements, and custom artwork can replace some of this, but at the moment JavaScript itself is a pure scripting environment with no comprehensive GUI toolbox. For many apps this will be a deal-breaker. It should also be stressed that one main drawback of this hybrid approach is that all of the JavaScript client code you deploy will be much more visible to hackers and code-thieves than the compiled, linked, and stripped code of traditional application binaries.

Figure 1. The changes in application code structure

Restructuring the Codebase

The hybrid application's codebase needs to be split into two totally separate modules, a "Client UI" (written in JavaScript) and a "Back-End" of supporting code written in Objective-C (or mostly Carbon if one is a die-hard traditionalist). Given the significant overlap between AppKit and DHTML, many kinds of applications can reduce their AppKit usage to the bare minimum of setting up menus and creating the main window. But not all of Cocoa can, or need be, replaced; the Foundation classes will still be useful since the front-end client will generally require some back-end services (like access to the local file system) that only the Foundation API can provide.

The end result of this code re-organization is a cross-platform DHTML-driven user experience spot-welded to a supporting native-code infrastructure. This infrastructure code can still access all of OS X's useful frameworks like CoreData, CoreAudio, DotMac, and even OpenGL, while the UI front-end can be relatively easily redeployed onto any modern, standards-compliant browser.

Nuts & Bolts -- Assembling the Application From Parts

A new hybrid WebKit application is most easily started as a regular Objective-C WebKit application. The basic idea is to: a) create a WebKit WebView spanning the application window; b) load an HTML text file from the application bundle's Resources folder into it; c) let WebKit and one's JavaScript code handle the UI from there. The following illustration gives a schematic overview of how a hybrid WebKit application can be structured:

Figure 2. Who loads what in a DHTML application

The HTML file can link in supporting JavaScript, CSS, and image files from the Resources folder with relative path referencing; for example backgroundImage = 'url(Images/image.png)'. Like other resources, we can add these files to the Xcode project and they will be copied into the Resources folder automatically.

Sample Code Walk-Through

To demonstrate this hybrid approach we will mash together two Apple-provided codebases: the "MiniBrowser" sample in /Developer/Examples/WebKit/, and the "Tile Game" Dashboard widget. This sample assumes you have Mac OS X 10.4 but the principles are the same for earlier OSs.

Step 1: Gutting the MiniBrowser Project

Copy the MiniBrowser project folder somewhere to work on, so you don't mess up the original. We'll first need to delete the document-oriented configuration of the project:

• Open up the target settings window by selecting %Edit Active Target 'MiniBrowser'% from the %Project% menu

• Click on the %Properties% tab selector

• Select the %HTML Document% item in the %Document Types:% list and click the minus button

Next, delete the MyDocument stuff -- .h, .m, and .nib -- completely. Open MainMenu.nib and delete the %History% submenu in the main menu bar. Next we have to root out all of the MiniBrowser's history-related things from AppController; AppController.h will become just a stub declaration:

@interface AppController : NSObject
@end
We need to modify AppController.m as follows:
#import "AppController.h"
#import "WebKitWindow.h"
@implementation AppController
- (void) applicationDidFinishLaunching: (NSNotification*)
      notification
{
   [[WebKitWindow alloc] initWithFile: @"TileGame.html"];
}
@end

Step 2: Adding the WebKitWindow class

We will now create new Cocoa Objective-C files for the WebKitWindow class: WebKitWindow.m and WebKitWindow.h. The header file's interface declaration will be:

@class WebView, WebScriptObject;
@interface WebKitWindow : NSWindow
{
   WebView* _web_view;
   WebScriptObject* _script;
}
- (id) initWithFile: (NSString*) resource_file;
@end

While the WebKitWindow.m implementation file contains:

#import "WebKit/WebKit.h"
#import "WebKitWindow.h"
@implementation WebKitWindow
// AppKit will beep if keypresses aren't caught, so eat them here:
- (void) keyDown: (NSEvent*) theEvent { }
- (BOOL) loadFile: (NSString*) resource_file
{
   NSString* resource_path = [[NSBundle mainBundle] 
resourcePath];
   NSString* partial_path = [resource_path 
stringByAppendingPathComponent: resource_file];
   // URLs require the 'file' scheme to be prepended:
   NSString* full_path = [NSString stringWithFormat: 
@"file://%@", partial_path];
   // Escape any illegal characters in the path:
   NSString* escaped_path = [full_path 
stringByAddingPercentEscapesUsingEncoding: 
NSASCIIStringEncoding];
   NSURL* file_url = [NSURL URLWithString: 
escaped_path];
   NSURLRequest* url_request = [NSURLRequest 
requestWithURL: file_url];
   
   [[_web_view mainFrame] loadRequest: url_request];
   
   return YES; /* TODO: error checking */
}
- (id) initWithFile: (NSString*) resource_file
{
   NSRect window_rect = NSMakeRect(100,100,400,300);
NSRect view_frame = NSMakeRect(0,0,400,300);
   self = [super initWithContentRect: window_rect
         styleMask: NSClosableWindowMask+NSTitledWindowMask
         backing: NSBackingStoreBuffered
         defer: NO];
   [self setTitle: @"WebKit"];
   [self setShowsResizeIndicator: NO];
   _web_view = [[[WebView alloc] initWithFrame: 
view_frame] autorelease];
   
   [self setContentView: _web_view];
   // Set the three WebView delegates to this object:
   [_web_view setResourceLoadDelegate: self];
  [_web_view setUIDelegate: self];
  [_web_view setFrameLoadDelegate: self];
   [self loadFile: resource_file];
   
   return self;
}
// this WebUIDelegate method will be called by the WebView when the view is ready:
- (void) webView: (WebView*) sender
      didFinishLoadForFrame: (WebFrame*) frame
{
   [self makeKeyAndOrderFront: self];
}
@end

Step 3: Merging the DHTML Content into the Project

Copy the following four items from the /Library/Widgets/Tile Game.wdgt widget bundle to your project directory: (see figure 3)

and add them to your project's %Resources% file group. When adding the Images folder, select the %Create Folder References% option in the dialog; this will make Xcode copy the entire Images folder (not just the images themselves) into the Resources directory on every build.

Xcode as of 2.1 doesn't know .js, so it has just put TileGame.js into the wrong build phase. To correct this, dig into the project's %Targets% group in the left sidebar and drag the %TileGame.js% item from the %Compile Sources% build phase to the %Copy Bundle Resources% build phase.

Step 4: Modifying the DHTML Resources

This hybrid Cocoa/JavaScript application should be runnable now, but two tweaks can be made to the Tile Game resources to give us better UI behavior. First, modify the <body>

Figure 3. Borrow the Tile Game Dashboard widget's resources we (use the Finder's "Show Package Contents" contextual menu command to get inside the widget bundle)

tag in TileGame.html to look like:
<body onload='findImgs();' onselectstart="return false"
      ondragstart="return false">

These two additional <body> properties disable the usual browser functionality of allowing the user to select text and drag objects, respectively. (When coding up your DHTML UI in JavaScript you can re-enable this behavior on a per-element basis.) Lastly, we need to make an addition to the body's style declaration in TileGame.css:

   overflow: hidden;

to stop scrollbars from automatically appearing whenever a tile object overlaps the body's frame.

Run the app; you should now have liberated the Tile Game code from the Dashboard prison and see it functioning as a proper desktop application.

Step 5: Hooking Up The JavaScript and the Objective-C Codebases

We have now reached the nut of this article: getting JavaScript and Objective-C talking to each other. I've included the relevant Apple documentation links in the References section of this article, so I will just present a general overview of the steps involved.

We already have the first step done: setting the WebView's delegates to us so we can get callbacks on various events that WebKit deals with. We can now add two more WebUIDelegate callbacks to the WebKitWindow implementation:

// this WebUIDelegate method will be called whenever window.status is written to.
- (void) webView: (WebView*) sender setStatusText: (NSString*) text
{
   NSLog(@"status> %@", text);
}
// this WebUIDelegate method will be called with the window.alert() message
- (void) webView: (WebView*) sender runJavaScriptAlertPanelWithMessage: (NSString*) message
{
   NSLog(@"alert> %@", message);
}

Now whenever the JavaScript side issues an example window.alert('some message') call or directly sets the window.status = 'another message' window property, our Objective-C delegate object will receive the particular message string via WebKit.

A good place to test this JavaScript ==> WebKitWindow "console" string passing is in the findImgs() function, which, being the HTML document's "onload" event handler, will be called only once at app launch.

The next delegate method to add to WebKitWindow's implementation is this WebFrameLoadDelegate method:

- (void) webView: (WebView*) webView 
      windowScriptObjectAvailable: (WebScriptObject*) 
      windowScriptObject
{
   // retain the script object for future calls:
   if (!_script)
      _script = [windowScriptObject retain];
   // publish this instance to JavaScript:
   [_script setValue: self forKey: @"webkit_window"];
}

This method does two key things: it first retains windowScriptObject; this is JavaScript's global environment object; with it, Objective-C code can call JavaScript functions like so:

   [_script callWebScriptMethod: @"test" withArguments:
      [NSArray array]];

As covered in the Apple documentation, the withArguments: array can be stuffed with NSNumbers, NSStrings, and NSArrays (unfortunately, the NSDictionary class is not bridged at this time). Note that, apparently, one can't call JavaScript functions in this particular delegate method (I guess the script object is not really 'available' quite yet), so to test this now you would have to put the above -callWebScriptMethod:withArguments: call in WebKitWindow's -keyDown: method, define a JavaScript function to call, and hit a key when running the application.

The second statement of the above method declaration:

[_script setValue: this forKey: @"webkit_window"];

"publishes", or exposes, this object to the JavaScript environment; that is webkit_window becomes a defined property of the JavaScript global environment. NSNumber, NSString, and NSArray objects published this way will be bridged as native (Number, String, Array) types to the JavaScript environment, while objects like WebScriptWindow will have their instance methods (but not any instance variables) made visible.

The Apple documentation is sort of unclear on this, but before JavaScript code can call a bridged object's methods, we must add the following static method to the object's (in this case WebKitWindow's) implementation declaration:

+ (BOOL) isSelectorExcludedFromWebScript: (SEL) sel
{
   return NO;
}

This informs WebKit that it's cool for JavaScript to call any of the instance methods of this object. 
To round-trip test Obj-C ==> JavaScript ==> Obj-C, you can change -keyDown: to:

- (void) keyDown: (NSEvent*) theEvent
{
   [_script callWebScriptMethod: @"test2" withArguments:
         [NSArray array]];
}

and add a WebKitWindow instance method for the JavaScript to call:

- (void) helloFromJavaScript
{
   NSLog(@"JavaScript says hello");
}

and, finally, in TileGame.js:

function test2()
{
   if (typeof(webkit_window) != 'undefined')
      webkit_window.helloFromJavaScript();
   else window.alert("sorry, I can't see the bridge");
}

Now when you run the application and press a key you should see the two environments successfully calling each other. Note that Objective-C method names with colons and other punctuation characters will be mangled when exposed to JavaScript; this is documented in the "Using Objective-C From JavaScript" section of Apple's "Introduction to Safari JavaScript Programming Topics" article.

Discussion

The JavaScript Environment

With this basic bridging functionality in place, the JavaScript environment can become a convenient platform for the OS X application creator. As a C/C++/Objective-C/Objective-C++ programmer who has dabbled in Python and Ruby, I've found working in this DHTML/JavaScript environment to be very enjoyable and surprisingly productive. The language features that are responsible for this efficiency include:

• Everything being an object, and the dynamic typing of objects. You can pass a String to a function that normally takes a Number, which can be useful if your code is designed to handle this case. Objective-C also allows this polymorphism, but I've found that JavaScript's implicit type declaration tends to encourage this.

• Functions being first-class objects, making JavaScript quite similar to the LISP of my youth (but with a nifty C syntax). You can pass closures around; in fact, creating class member functions in JavaScript involves explicitly assigning function objects to class member variables (which are called "instance properties" in JavaScript-speak).

• The simplicity of JavaScript and its supporting language environment. There's a lot less to get in your way; the language is very lightweight and very flexible. There are none of Objective C's vestigial pointers to structs, [Bizarre [[nested bracket] sequences]], or retain/release memory management hassles. There is also enough syntactic sugar in JavaScript to rot your teeth.

"Gotchas" have included this very dynamic nature of JavaScript. You can indeed pass a String to a function that normally takes a Number, which can be disastrous if your code is not designed to handle this case. Also, one of the odd features of JavaScript is that functions do not have a fixed this implicit argument bound to them when called. The this can be the global environment in certain situations, which is somewhat mind-bending until you get used to it. And there is no real strong idea of class inheritance -- you have to roll your own object hierarchies when you initialize new objects.

Another major weakness that I have found working in JavaScript is the total lack of debugging facilities in WebKit. When you break something, your app just stops working. I've found maintaining a parallel working test-harness in Mozilla Firefox, to be a great sanity-saver when trying to figure out what has gone wrong, since Firefox has an ace syntax checker that prints more informative error messages to the browser's debug JavaScript console than Safari's.

Beyond DHTML

Outside of manipulating the DOM, for example adding zillions of tiny <div> elements to produce what looks like pixel graphics, JavaScript has zero graphics capability. Recently, Apple has bridged the gap, offering the WHAT working group the <canvas> element, a pretty close facsimile of CoreGraphics / "Quartz". This canvas element is basically a non-resizable image element that you can issue 2D immediate-mode rendering primitives to. It does not currently feature text output, but it is a trivial task to overlay the canvas element with text nodes in the DOM. Canvas is supported by WebKit as of 10.3.9, and also Firefox 1.5. But, when using the canvas element, be warned that Bezier curves are rather broken in WebKit as of 10.4.2 (they work fine in Firefox 1.5, however).

Development Environment

As mentioned above, I just use Xcode for editing source files and Firefox's JavaScript Console for catching syntax errors. It's pretty old-school, but so far it has worked for me.

Deployment

WebKit is fully functional with 10.3.9 and up, and is supported back to 10.2.7, or 10.2.x with Safari installed. Mozilla Firefox offers a reasonably compatible execution environment for other OS platforms; my own not-trivial application looks and feels identical, to the pixel, when compared running on WebKit and with running in Firefox on Windows.

Of course, the back-end code you write will not run in Firefox at all. Data persistence and/or local storage are the biggest challenge for browser-based DHTML applications. During the bring-up of my own app in Firefox, I just stashed read-only data in hidden text nodes in the DOM, and used the browser cookie mechanism for weak (but better-than-nothing) local storage functionality. The best solution for getting data persistence within the browser environment might be accessing remote servers over the Internet via the XMLHTTPRequest object. See (Garrett 2005) for an examination of this technique.

References

Introduction to Web Kit Objective-C Programming Guide

http://developer.apple.com/documentation/Cocoa/Conceptual/DisplayWebContent/index.html

Introduction to Safari Web Content Guide http://developer.apple.com/documentation/AppleApplications/Reference/SafariWebContent/index.html

Using JavaScript From Objective-C

http://developer.apple.com/documentation/Cocoa/Conceptual/DisplayWebContent/Tasks/JavaScriptFromObjC.html

Introduction to Safari JavaScript Programming Topics

http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/index.html

Drawing Graphics with Canvas

http://developer.mozilla.org/en/docs/Drawing_Graphics_with_Canvas

Core JavaScript 1.5 Reference

http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference

Garrett, Jesse James. "Ajax: A New Approach to Web Applications". (February 2005).

http://www.adaptivepath.com/publications/essays/archives/000385.php

Goodman, Danny. Dynamic HTML: The Definitive Reference. 2nd edn.

http://www.oreilly.com/catalog/dhtmlref2

Meyer, Eric A. Cascading Style Sheets: The Definitive Guide. 2nd edn.

http://www.oreilly.com/catalog/css2

O'Reilly, Tim. "What is Web 2.0?". (September 2005).

http://www.oreillynet.com/lpt/a/6228

Smith, Dori. "What is JavaScript?". MacTech Magazine (formerly MacTutor) 14:5 (May 1998).

http://www.mactech.com/articles/mactech/Vol.14/14.05/WhatisJavaScript/index.html

---

Troy Dawson is a former Apple software engineer now working on things that interest him related to Macintosh and web development. You can reach him at troydawson@earthlink.net.