[Note: This blog post is out of date. For up to date information on Dojo Offline please see the official web page.]

The last few weeks we’ve been putting together our API for the Dojo Offline Toolkit (DOT). How will a programmer use this toolkit in their work? How will it be integrated into their applications?

Last week we reported on addressing usability for offline access, with offline mockups of popular web apps. Usability is just as important for programmers as it is for end-users, it just takes a different form: the API, or Application Programmer Interface. Getting the API right is just as important as the UI; programmers need the love too.

Look Mah, No Proxy!

Before we dive down into the API, I want to share a nice surprise: the Dojo Offline Toolkit API has been designed to not necessarily need a web proxy. For example, if your browser has native support for offline access, then we don’t need to download the small web proxy — the browser will simply cache these offline resources. The plan for Firefox 3 is to natively support such an API — in this scenario, Dojo Offline could simply use the browser’s offline cache rather than requiring you to download the web proxy.

Here’s an even nicer thing: as soon as we finish the JavaScript API you see in this blog post, you can start using Dojo Offline even without the full, local web proxy being done. How is this possible? Well, if you use the trick discovered by Julien Couvreur and set your web server headers to correctly send HTTP/1.1 caching info (like my Moxie application does), then the browser cache will store your files for offline use. This is appropriate for prototyping and getting beginning applications out there; the web proxy is an optimization meant to improve the reliability of offline cached files. Without the web proxy browser cache misses are possible, which would translate into UI resources not being available when offline, but this might be good enough for prototyping and for some applications (in fact, Scrybe works this way if you look carefully at their screencast).

And here’s the really nice thing: when the full web proxy becomes available, your application will require very little change (in fact, one change, as you will see below) to gain the improved UI reliability the web proxy offers.

Let’s quickly see how DOT achieves this generality. DOT refers to the ability to truly store web files offline as a durable cache, rather than a web proxy; a durable cache is a more generic term, since it could be backed in any number of ways: by the web browser with native support or by the DOT local proxy. By default, DOT requires a durable cache; this can be changed with offline.requireDurableCache = false. During startup, the default UI queries if a durable cache is required; if so, we see if one is available; if it is not, we prompt the user to install one. When a durable cache becomes available (such as the DOT local proxy), the toolkit can simply prompt the user to download it.

KISS – Keep It Simple

Let’s start with the simplest example of programming against Dojo Offline. The philosophy behind the Dojo Offline API is to have sensible defaults for everything (thanks DHH!), while providing framework configuration hooks that can be overridden if you want to take things over and go past the defaults.

Our example application will be a kind of web-based Outlook, with emails and tasks. Users can read and create emails offline, and also update their task list when away from the network. Everything below will be pseudo-code to illustrate how Dojo Offline can be used. Please keep in mind that this is just the planned API and is not available yet — this is all design work in preparation for coding this week; also note that the API is sure to change both during development as well as after the first version is released. Expect it to evolve in mid-air as we slam into reality.

Let’s look at the full pseudo-source code for our example application, which we will break down and explain in pieces. Don’t worry — all of this will be explained in detail below.

Our HTML file will look something like the following:

Parts of my application's UI here