The Flow of Events
The Flow of Events
So far, I’ve talked about offline web applications, the cache manifest, and the offline
application cache (“appcache”) in vague, semimagical terms. Things are downloaded,
browsers make decisions, and everything “Just Works.” You know better than that,
right? I mean, this is web development we’re talking about. Nothing ever “Just Works.”
First, let’s talk about the flow of events, specifically DOM events. When your browser
visits a page that points to a cache manifest, it fires off a series of events on the
window.applicationCache object, as I describe below. I know this looks complicated,
but trust me, this is the simplest version I could come up with that didn’t leave out
important information. Here’s the process:
1. As soon as it notices a manifest attribute on the <html> element, your browser fires
a checking event. (All the events listed here are fired on the window.applicationC
ache object.) The checking event is always fired, regardless of whether you have
previously visited this page or any other page that points to the same cache
manifest.
2. If your browser has never seen this cache manifest before:
• It will fire a downloading event, then start to download the resources listed in
the cache manifest.
• While it’s downloading, your browser will periodically fire progress events,
which contain information on how many files have been downloaded already
and how many files are still queued to be downloaded.
• After all resources listed in the cache manifest have been downloaded success-
fully, the browser fires one final event, cached. This is your signal that the offline
The Flow of Events | 141
web application is fully cached and ready to be used offline. That’s it; you’re
done.
3. On the other hand, if you have previously visited this page or any other page that
points to the same cache manifest, your browser already knows about this cache
manifest and may already have some resources in the appcache. In fact, it may have
the entire working offline web application in the appcache. So now the question
is, has the cache manifest changed since the last time your browser checked it?
• If the answer is no, the cache manifest has not changed. In this case, your
browser will immediately fire a noupdate event. That’s it; you’re done.
• If the answer is yes, the cache manifest has changed. In this case, your browser
will fire a downloading event and start redownloading every single resource listed
in the cache manifest.
While it’s downloading, your browser will periodically fire progress events, which
contain information on how many files have been downloaded already and how
many files are still queued to be downloaded.
After all resources listed in the cache manifest have been redownloaded success-
fully, the browser will fire one final event, updateready. This is your signal that the
new version of your offline web application is fully cached and ready to be used
offline. The new version is not yet in use. To “hot-swap” to the new version without
forcing the user to reload the page, you can manually call the window.applicationC
ache.swapCache() function.
If, at any point in this process, something goes horribly wrong, your browser will fire
an error event and stop. Here is a hopelessly abbreviated list of things that could go
wrong:
• The cache manifest returned an HTTP 404 (Page Not Found) or 410 (Permanently
Gone) error.
• The cache manifest was found and hadn’t changed, but the HTML page that
pointed to the manifest failed to download properly.
• The cache manifest was found and had changed, but the browser failed to down-
load one of the resources listed in the cache manifest.