This is my personal blog. The views expressed on these pages are mine alone and not those of my employer.

Thursday, February 21, 2008

Gears PubTools: Offline Enable Content in Minutes

I've created some simple utilities to make it much easier to use Google Gears without having to delve into JavaScript. This new open source library, named Gears PubTools, is a simple collection of JavaScript files that make it easy for content authors to work with Google Gears with just a little bit of HTML. With PubTools, you can easily offline-enable your content within minutes:

- Point to a Gears manifest file (a special file that lists all the pages to take offline) with a simple HTML attribute:
<html gears-manifest="manifest.js">
- Create a desktop shortcut icon that points right to your app and
use a custom image:
<html shortcut="true" gears-manifest="manifest.js">
<head>
 <link rel="shortcut.icon" title="32x32" href="icon32x32.png"></link>
- You don't even have to write the manifest file yourself! PubTools includes a simple bookmarklet that developers can drag to their browser's toolbar. Just navigate to the web pages you want offline, press the "Generate Manifest" bookmarklet, and a dialog will appear with the full manifest file generated for you ready to cut and paste into a file.

Quick Start

Want to get started using PubTools? First check out the simple demo page, then get started:

1) Use the PubTools bookmarklet to create a Gears manifest file. Go to src/manifest-bookmarklet.html to get the bookmarklet and follow the directions. Save this to a file, such as manifest.js.

2) In the web page you want to offline-enable, pull in the PubTools JavaScript file:
<script type="text/javascript" src="pubtools-gears.js"></script>
3) Point to your Gears manifest file:
<html gears-manifest="manifest.js">
4) If you want a desktop shortcut icon, add shortcut="true":
<html gears-manifest="manifest.js" shortcut="true">
You must provide at least one icon in PNG format; possible sizes are 16x16, 32x32, 48x48, 128x128. Providing all of them is best to allow the OS to choose the best one. Specify them using a LINK tag:
<link rel="shortcut.icon" title="16x16" href="icon16x16.png"></link>
<link rel="shortcut.icon" title="32x32" href="icon32x32.png"></link>
<link rel="shortcut.icon" title="48x48" href="icon48x48.png"></link>
<link rel="shortcut.icon" title="128x128" href="icon128x128.png"></link>
By default, PubTools chooses intelligent defaults for the shortcut icon. You can override these if you wish using META tags:
<meta name="shortcut.name" content="Test Application"></meta>
<meta name="shortcut.description"
content="An application at http://www.test.com/index.html"></meta>
<meta name="shortcut.url" content="http://www.test.com/index.html"></meta>
Most of these have sensible defaults and can be left out:
'shortcut.name' defaults to the HTML TITLE element if not present.
'shortcut.url' defaults to the page's URL if not present.
'shortcut.description' is optional and defaults to the string
"Offline Web Application"

Note that shortcut icons are only in the development version of Gears; the currently deployed version of Gears does not support shortcuts yet. PubTools will correctly continue to function if the user's installed version of Gears doesn't support shortcuts.

5) PubTools provides a simple default, optional UI for the user. To get this UI, add an element with the magic ID "gears-pubtools-offline-widget" into your HTML:
<div id="gears-pubtools-offline-widget"></div>
When the page loads, the user will see "Download Offline." When pressed, everything in the manifest is made offline and the shortcut icon is created if desired, with the user given feedback on the process. Now, the user will see "Delete Offline." By pressing this a user can delete the offline resources and start over at a later date.

If you don't want the default UI, your custom UI can call PubTools.downloadOffline() to initiate the download of offline resources, and can call PubTools.deleteOffline() to delete the offlined content. These can only be called after the page is loaded.

6) That's it! You're done. See the demos/ directory for a demo and boilerplate you can copy.

Quick note: Make sure not to list the pubtools-gears.js file in your manifest file. The manifest generator takes this into account to leave this out, but if you create it by hand leave it out. We do a trick where when you are offline we simply don't have the file, which doesn't display the default UI to the user since it makes no sense to show that when offline.

I've opened a code.google.com open source project for PubTools. I've done a bunch of QA testing on it, but make sure to file any bugs you might find. If you have patches send them in to me.

Labels: , , ,


// posted by Brad Neuberg @ Thursday, February 21, 2008
Comments: Post a Comment



Links to this post:

Create a Link



<< Home

This page is powered by Blogger. Isn't yours?

Subscribe to Posts [Atom]