Completing your native Mac OSX App built in HTML5

Note: this is a continuation of How to embed HTML5 into a native Mac OSX app. This tutorial uses Xcode Version 4.0.1.

So having gone through the first tutorial, you should now have a bare-bones native OSX application running your HTML5 program. Let's open that same project in Xcode (example on GitHub) and finish it up! I'll use WebViewExample as the name of this tutorial project, but just like last time, yours can be whatever you like.

Adding an icon to your app

To set the icon that appears in the dock, Finder and other views, follow these steps:

  1. First you need an Apple Icon Image file. To make one yourself, open up the Icon Composer application (mine is located in /Developer/Applications/Utilities/Icon Composer.app). For the sake of speed you can use OnslaughtArena.icns.
  2. In Xcode's left sidebar, drill down into WebViewExample / Resources.
  3. Drag your .icns file into the Resources folder.
  4. Still in the Resources folder, open the WebViewExample-Info.plist file.
  5. In the "Key" column, find the row with the value "Icon file".
  6. Set the value of this row to the name of your .icns file (eg, OnslaughtArena.icns).

Closing the window should close the application

For those unfamiliar with OSX, I'll quickly describe what this means. In OSX, you can have an application open without any windows. This is very different from Microsoft's Windows operating system where if all the windows are closed, the application is no longer running. This can create an awkward user experience, so there must be a way to bring windows back. This flow doesn't really make much sense for games, so a good workaround is to close the application when all windows are closed.

Be sure to do this; we got rejected the first time we submitted because we did not enable this feature! Here's the reason from Apple:

We have found that if the user closes the app window, there is no way for the user to reopen the app without having to quit and relaunch the app.

Fortunately the fix is easy.

  1. In Xcode's left sidebar, drill down into WebViewExample / Classes / WebViewExampleAppDelegate.m.
  2. In the awakeFromNib method, add this line just above the closing bracket: [window setDelegate:self];.
  3. Add this method after the awakeFromNib method:

- (void)windowWillClose:(NSNotification *)aNotification {
	[NSApp terminate:self];
}

That's it! Now when you close your application's main window, the application should quit. Note: this works great but it generates the warnings "notice: Semantic Issue: Passing argument to parameter 'anObject' here" as well as "Class 'WebViewExampleAppDelegate' does not implement the 'NSWindowDelegate' protocol".

Logging errors

Xcode can be a bit daunting to newcomers, but fortunately it's very easy to send messages to the log. It can be done with code like this:

NSLog(@"example message");

(These messages should appear in the main Xcode window, in the very bottom.)

Enabling localStorage

It seems that, by default, localStorage will not persist data in an embedded WebView as expected. Here's how to enable it:

  1. In Xcode's left sidebar, drill down into WebViewExample / Classes / WebViewExampleAppDelegate.m.
  2. Add this code to the top of the awakeFromNib method: WebPreferences *prefs = [webView preferences];.
  3. Then add this line just below that: [prefs _setLocalStorageDatabasePath:@"~/Library/YourProjectName/LocalStorage"];. (Be sure to use the name of your project intead of "YourProjectName".)

It's important to name the folder that localStorage saves to with the same name as your application (eg, Onslaught! Arena saves to "~/Library/OnslaughtArena/LocalStorage")! Apple will reject your app if it puts data somewhere unexpected.

Note: this may generate the warning "'WebPreferences' may not respond to '-_setLocalStorageDatabasePath:'".

Summary

Onslaught! Arena

Your application should now meet the bare essentials for submission to the Mac App Store, and you could be reaching a wider audience with your HTML5 app in no time (pending Apple's approval …). Did I miss anything you were hoping to know about? Any steps not work for you? Please let me know.

Bonus: if you want to see what kind of quality you can get out of a native OSX HTML5 app, we just dropped the price of Onslaught! Arena in the Mac App Store to $1.99! See HTML5 in action for yourself.