As promised last week here's a simple demo of Gears working with Domino. And when I say simple...

How To Test It

The proof of any pudding is, as they say, in the tasting. So, err, let's eat.

If you visit the demo page and don't have Gears installed you should see a prompt to install it. Either do it that way or just go here and do it.

Come back to the demo page and you should see a security warning from Gears asking for permission for the site to use it. Just click on the trust box and press Allow. Go on, you know you trust me.

With the warning gone you'll see the "No documents found" message we've all come to know and love. That's because the page only shows documents created from your IP address. I did this so that other people don't work offline on the same data and not produce odd results when testing.

Click Add New Row and create a few documents in the view.

While you remain online the Update buttons simply use Ajax to update the document directly on the server.

Now press the Go Offline button. The "view" should be replaced by a message about downloading the data. This message remains while Ajax fetches all your documents and stores them in a local database (SQLite) on your PC. The green online box should turn red to signify offline status.

Pressing the Update button while offline will just update the field value directly to the local SQL database. When you've made some changes and are ready to go back online just press the button to do so and an Ajax requests sends details of all the modified documents back to the server where they're updated.

How Do I Know It's Really Offline!

For the sceptics there's an easy way to test this really is working offline. Press the Go Offline button again. Once the local view appears and the box turns red you can put your browser in offline mode too by choosing Work Offline from the File menu. If you don't trust that then pull you network cable out or turn your router off. Trust me though - it does work.

Just remember to re-enable your connection and/or browser before trying to put the app back online.

How Does it All Work?

When you press the Go Offline button Ajax fetches all the latest documents from the server. Some JavaScript calls to the Gears Database API then stored details of each document in a SQL table.

Once the data is stored offline Gears then fetches the files that make up the application. It does this by referring to a manifest file. Here's the contents of the manifest file for the demo app

{
  "betaManifestVersion": 1,
  "version": "v1.0",
  // URLs to be cached (relative to the manifest URL)
  "entries": [
	{ "url": "demos.gears", "src": "demos.gears?Open&offline=true" },
	{ "url": "gears/init.js" },
	{ "url": "gears/GGD.js" },
	{ "url": "css/gears.css" },
	{ "url": "images/gears/logo.gif" },
	{ "url": "tools/gearsquery.html?open&dbinfo=domino" }
    ]
}

In it is a list of the files that Gears downloads to your PC and stores in a special folder, where it serves them from in offline mode.

Gears is not using the browser's cache! To prove it go offline and then clear the browser's cache. Revisit the URL you were at when you went offline and it's still there!

Notice one key trick in the manifest file. The first entry is to the main page "demo.gears" but we've told Gears to "cache" the page at "demos.gears?Open&offline=true". With this parameter passed the Domino form can be told not to send the view as part of the page (we build then with JavaScript in offline mode) and to make the status area default to red for offline. View the source of the page in online and offline mode to compare.

When you go back online this local store of files is removed to make sure you're not using the "cache" from then on.

Summary

It's a very simple demo but hopefully it proves the concept. What I didn't mention is that it works on handhelds devices too. If you want to try this out but don't have one to hand, try an emulator.

Obviously this demo can't be taken and used as is for most projects. It would be nigh on impossible to produce a solution that's fits all scenarios. Whether Gears can be of any use to you or not depends on lots of things...

What about the download? I'll make that available tomorrow once you've had chance to debug it for me.