Auto Updates and more for Offline First Applications
Switch branches/tags
Clone or download
Pull request Compare This branch is 7 commits behind hoodiehq-archive:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
admin-dashboard
hooks
test
.gitignore
README.md
hoodie.appcache.js
manifest-generator.js
package.json
worker.js

README.md

appCache Hoodie Plugin

Auto Updates and more for Offline First Applications

Hoodie has offline-support built in—for data. If you want to make your app work offline as well, you have work with Application Cache – and it's a douchebag.

Until now.

The appCache Hoodie Plugin gives you a JavaScript API that gives you full control on whether you want to make your app work offline or not. It provides a beautiful JavaScript API for the initial caching, for updating, and much more.

The appCache Hoodie Plugin is basically a wrapper around The appCache Nanny, with the addition that it serves an auto-generated manifest.appcache file and appCacheNanny's appcache-loader.html.

No extra setup needed, you can make your app work offline with a single line of JavaScript.

Installation

hoodie install appcache
# this is needed as temporary workaround for
# https://github.com/hoodiehq/hoodie-plugin-appcache/issues/7
npm install -S appcache-nanny

Usage

First thing to learn is that you won't add manifest="path/to/manifest.appcache" properties to <html> tags any more. Your app doesn't get cached automatically, you have to start the caching explicitely:

hoodie.appCache.start().then(showAppIsCachedNotification)
// NOTE: start() does not yet return a promise: #5

That's it. Not only does your app work without internet connection now, it also automatically starts to check for update with an interval of 30 seconds.

Here's a list of all avialable methods:

// start initial caching & auto-updating, returns promise
hoodie.appCache.start({
  // in ms, defaults to 30000
  checkInterval: 10000,

  // in ms, defaults to 30000
  offlineCheckInterval: 5000,

  // set a path to your custom manifest loader,
  // defaults to /_api/_plugins/appcache/_api/loader
  loaderPath: '/appcache-loder.html',
});
// manually check for updates, returns promise
hoodie.appCache.update()
// stops auto-updating, returns promise
hoodie.appCache.stop()
// returns true / false
hoodie.appCache.hasUpdate()
// returns true / false
hoodie.appCache.isSupported()
// returns true / false
hoodie.appCache.isCheckingForUpdates()
// get / change settings
hoodie.appCache.set('checkInterval', 20000)
hoodie.appCache.set('offlineCheckInterval', 10000)
hoodie.appCache.set('loaderPath', '/new/appcache-loader.html')
var checkInterval = hoodie.appCache.get('checkInterval')
var offlineCheckInterval = hoodie.appCache.get('offlineCheckInterval')
var loaderPath = hoodie.appCache.get('loaderPath')

The appCache comes also with a list of events that you can react on

hoodie.appCache.on('update', handleUpdate)
hoodie.appCache.on('error', handleError)
hoodie.appCache.on('noupdate', handleNoUpdate)
hoodie.appCache.on('downloading', handleDownloading)
hoodie.appCache.on('progress', handleProgress)
hoodie.appCache.on('cached', handleCached)
hoodie.appCache.on('updateready', handleUpdateReady)
hoodie.appCache.on('start', handleStart)
hoodie.appCache.on('stop', handleStop)
hoodie.appCache.on('init:downloading', handleInitialDownloading)
hoodie.appCache.on('init:progress', handleInitialProgress)
hoodie.appCache.on('init:cached', handleInitialCached)

How it works

The appCache Hoodie Plugin automatically scans your app's www/ folder and adds all assets to the manifest.appcache to make them available offline. Each time an asset changes the manifest.appcache gets changed to trigger an update.

hoodie.appCache.start() add's a hidden <iframe> to the page that loads appcache-loader.html. That's an empty HTML file has the manifest property on its <html> tag to start or update the local cache. Both files are served from the appCache Hoodie Plugin's hook API.

Fine Print

appCache Hoodie Plugin has been authored by Gregor Martynus, proud member of The Hoodie Community, with help from Michael Oneppo. Please support our work: gittip us.

License: MIT