Whilst it took a while to get my head round exactly how application cache manifest files work I have found them to be very useful. Here are my notes on the subject.
Workflow
I found the workflow easier once I’d written it down. This is my approximation of it:
- Request for file made, browser sees manifest reference
<html manifest=”site.appcache">
- Server responds with text file served as mime type “text/cache-manifest”
- Browser checks Cache File
- Never seen before:
- Download files: Fire progress events for each
- No Error: Fire cached event
- Error: Throw error event
[End]
- Seen file before
- Manifest changed? NB: not ‘any file listed changed’ i.e. the manifest file’s content itself has to have been altered, not just the date/time stamp (see below for more information).
- Yes
- Download files: Fire progress events
- No Error: Fire cached event
- Error: Throw error event
[End]
- No: Fire noupdate event
[End]
NB: Once successfully cached, a browser will serve all cached files from it’s cache, not from the server. Theoretically this should be the case even if the cache is updated until window.appCache.swapCache() is fired, although I’ve found some browsers handle this situation differently. It can make for frustrating testing.
Possible Errors
An error is possible at any stage in this process. I’ve listed some of the common one’s below:
- Manifest file not found
- Manifest served with wrong type (typically just as text).
In Apache Web Server you can alter this by adding the following to the config file:
AddType text/cache-manifest .appcache
In IIS you can alter the manifest mime type by adding the following to web.config in the application root:
<configuration>
<system.webServer>
<staticContent>
<remove fileExtension=".appcache" />
<mimeMap fileExtension=".appcache" mimeType="text/cache-manifest" />
</staticContent>
</system.webServer>
</configuration>
- ANY of the files listed in the manifest do not download correctly.
Theoretically this should also refer to ALL dependant files (e.g. images) too but I’ve noticed this is browser and platform dependant.
- Browser stubbornly refuses to show updated file despite it being updated on the server.
Once successfully cached, the browser will continue to serve a file from it’s cache not from the server, except:
- If it is specifically excluded from the cache by being listed in the “NETWORK:” section.
- The manifest file is altered (see below).
- It might still be served from the cache even if the manifest is re read, until swap cache is called.
- Manifest file isn’t re-read:
A common reason for this is that the file’s content hasn’t changed, but the date time stamp has been. A common solution to this is to add a comment with a date/time stamp e.g. #05/11/2011 12:34
In Conclusion
Working with manifests can be a very frustrating business BUT it is also very rewarding when the application runs successfully offline. My advice would be to turn off the caching until you’re ready to test it, then get ready to pull your hair out!
I found a very
useful script which helped me
debug de mystify the app cache browser behaviour posted by
Ben Nadel. Thanks Ben!
References
https://www.w3.org/TR/2011/WD-html5-20110525/offline.html
http://www.html5rocks.com/en/tutorials/appcache/beginner/http://diveintohtml5.info/offline.html
