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


The best way to start development on a programming framework is to ground it in the kinds of user interfaces it will be used in. This ensures that you don’t create astronaut architectures that have no real world use.

The first step in creating the Dojo Offline Toolkit is to therefore figure out what offline web applications might look like. This will help us determine what to include in the Dojo Offline API and what to leave out, and will also be bundled as a simple HTML/CSS template that developers can easily drop into their applications.

SitePen kicked this off by creating offline-enabled mockups of three popular and useful web applications: Gmail, Blogger, and a corporate portal named Adenine. For all three the goal is to find a consistent, simple user-interface for offline web applications.


We start with a mockup of an offline-enabled Gmail (click on any of the images to view them full-size):

The first thing to notice is the addition of a new widget on the left-hand side of the page, the Offline Info widget. This widget encapsulates all of our offline functionality for Gmail.

If the Dojo Offline Toolkit is installed and you sign into Gmail, Gmail will automatically download your 100 newest emails into the offline cache. Now you can access Gmail offline to read your newest emails or compose new ones. When you sign back on your emails will be automatically synced and uploaded:

What happens if the Dojo Offline Toolkit is not installed? Here’s what you see:

Simple! Clicking the ‘Learn How’ link takes you to a page with the following getting started text:

Are you interested in using Gmail offline?It’s simple with the Dojo Offline Toolkit, a free open source utility that makes it easy for your favorite web applications to work, even if you’re offline. Now you can access your data even when away from the network!To get started:

  1. Download the Dojo Offline Toolkit, a small (200K) utility that helps this web site work offline. This tool is secure and safe for your machine, and should take just a few seconds to download. It will work across Windows, Linux, and Mac OS X.
  2. Double-click the installer on Windows and Mac OS X to install. For Linux, the installer is a small Firefox extension — approve the install.
  3. To access this website even when offline, drag the following link to your desktop: Run Gmail.
  4. Double-click the link on your desktop to start this web application, even if offline.

See how SitePen can work for you

This page makes it easy to get going with DOT — the ‘Download’ link will automatically select the correct download of DOT for your platform. The ‘Run Gmail’ link can be dragged to your desktop, providing an easy icon to double-click to run Gmail even when you’re offline. This will open your web browser and show the Gmail UI, along with your offline data.

Odds & Ends

Don’t forget that our goal is to find a relatively generic UI for offline web apps, so SitePen has to define the edge conditions for some of this and provide a bit more detail here.

Here’s the full sequence of syncing messages. First, we download the web application’s user-interface into the offline cache if that has never been done before, or update parts that are new:

The status messages give the percentage of completion so far, along with various messages. Next, we upload anything that is new in the offline cache, like new emails:

Then, we fetch the new stuff:

Finally, we either succeed:

Or we fail:

For an error, the little ‘details’ link will pop up a window with error details returned by the server; Dojo Offline apps can return any appropriate string here.

What happens if there are conflicts between local and remote data? This won’t happen for Gmail, since it is basicly a single-user application, but you could imagine it for Google Docs, an online word processor. For the first version of Dojo Offline we make an important decision: the server must make a defacto choice for data merges and conflicts, without a “merge” user-interface for the end-user. This is application specific, so a Google Docs might simple merge a user’s local document with the remote one. If there is a conflict, it could make an application-specific choice to simply use the data from the newest version of the document.

The decision to not support a complicated conflict/merge UI in Dojo Offline currently is an important one to reduce the complexity of this first iteration. Quite alot can be done by having the server simply choose how to merge and decide between conflicts in a non-UI way; if the server chooses, it can save both versions of the data for later presentation for the user, with two different document filenames, for example.

If automatic merging or conflict resolution occurred on the server, the user is notified of this:

If a user clicks the “(details)” link, a popup window will appear with text returned by the server that indicates how merging or conflict resolution might have occurred, similar to the log the Palm Pilot software uses after a sync (which also does automatic merges, btw). This should be terse and not confusing, such as “The document ‘foobar’ was changed on the server, but your version is newer — your’s was used.”

There is also a timestamp on when the last sync occured, which in this case is “Yesterday at 9 AM”:

Under this are the number of unique, new or modified items that might be in the user’s local cache but which are not available remotely; this is shown with the ‘3 modified offline items’ text. This will clear once a successful sync has occurred.

A user can also elect to synchronize manually, by pressing the Synchronize button themselves; this will kick off a synchronization session.

The Configure screen is also important; clicking the ‘Configure’ link will show configuration inline:

You can turn off offline caching completely by de-selecting ‘Enable offline’, and can force all synchronization to happen manually by de-selecting ‘Synchronize automatically’. You can imagine that some offline web apps will turn both of these off by default, or perhaps force all syncing to be done manually, such as for a web based book reader like the OpenLibrary where you can download books for offline reading, but manually.

After these two options offline web applications can place their own, simple, specific configurations; for Gmail, we can select how many new emails to download during synchronization.

The “Empty” link will empty your cache, while “Storage Settings” will show storage configuration for your data. For Dojo Storage, if hidden Flash is being used to persist the users data, for example, then this will show the Flash Storage configuration dialog.


An offline-enabled version of blogger has basicly the same widget as GMail’s Offline Info, but on the right-hand side of the page in the Blogger Dashboard:

On page load, Blogger would automatically download the last 10 blog posts, including images used in those posts. Individual blog posts indicate next to them if they have been locally modified (“modified offline”). If a blog post is not downloaded offline yet, the link “Download offline” appears, which when clicked causes the Offline Info widget to show download progress information, just like a sync. If you have local items that have not been synced, and have elected to sync manually, a small ‘(recommended)’ label will appear next to the Synchronize button.

The rest of the offline UI is pretty much the same, including the DOT download page, the syncing UI, and the configuration UI. The configuration UI might possibly have a small number of application-specific configuration, such as “[10] Newest Posts Synced,” where [] is a text field that can take a number.

Corporate Portal (Adenine)

Adenine is a web-based corporate portal; it was selected since it is indicative of how many corporate portals are used and structured. In Adenine, you have a standard portal dashboard; in this case, we have added the Dojo Offline widget:

Like the offline-enabled Gmail and Blogger, this application would auto-download whatever material is appropriate on page load, such as your recent calendar data, recent workflow tasks, and any custom databases you usually work with.

If you are working with a custom database, such as a Recruiting database that allows you to have a list of potential recruits, you can manually download a database or an item within that database; notice the ‘Download offline’ link in the right-hand corner of the web-spreadsheet.

Once clicked, ‘Download offline’ would cause the application to select an appropriate subset of this database to download locally, with a small DHTML popup window:

Here’s whats great about this UI: the ‘Download offline’ link and popup window are a generic way to indicate that you want to manually download an ‘item’ for offline access. The DHTML popup is a generic way to show syncing progress when the Offline Info widget is not visible for some screen. This could be applied to calendar events, specific blogs in an RSS reader, specific contacts in a sales database, etc.


With these mockups, SitePen now has a relatively generic set of templates for offline access for web applications. The Offline Info widget is a generic ‘overview’ area for offline operations; the ‘Download offline’ link is useful for manually bringing specific items offline; and the Sync DHTML popup is useful for providing offline download status when the Offline Info widget is not visible.

The next step is to use these UIs to help create an appropriate API for the Dojo Offline Toolkit, which is what SitePen will be doing the rest of this week. Tune in next week to see our proposed offline API.

Special Thanks

Special thanks to the following applications and libraries that were studied for this work:

  • SalesForce.com
  • Scrybe
  • Zimbra
  • ClickTime
  • Intel’s Occasionally Connected (OCC) Framework
  • Palm Pilot Desktop and Conduits

Thanks to Julien Couvreur and Dustin Machi for feedback on the UI mockups.