Application cache (appcache) is a powerful feature in HTML5. However, it does come with baggage. Many (see links below) advocated ferociously against it due to tricky issues it comes with. For someone who is just testing waters, these issues may throw them off grid. Knowing them before hand helps reduce some unpredictable effects.
Most important coding caveats about the manifest file and appcache.
- The main html file that declares the manifest is ALSO cached in app cache, even if it is not defined in CACHE section. So, if you update the html itself (master), in the manifest must change (a update-time-stamp) to see the changes (also will require user refresh or swapCache call)
- Manifest file must begin with the line "CACHE MANIFEST" instruction. Empty lines are treated just like comments in some browsers, so ensure it is the first one
- Manifest file must be served with a text/cache-manifest MIME type. Chrome seems to be fine otherwise, but you dont write for chrome alone, do you?
- Manifest file must be encoded with 8-bit Unicode Transformation Format (UTF-8) character encoding. This is as per W3C stature, may be easy to do, before you find yourself in trouble.
- The path URLs in CACHE section cannot have wildcards. (qualified - relative, canonical and external urls for each resource must be defined separately). URLs in NETWORK and FALLBACK sections can have wildcards (/api will apply for api directory tree; /api/1.html and /api/2.html but not /api2 or /api2/1.html) .
- URLs defined in CACHE are all or nothing. This is probably the biggest issue when you use external URLs, your app is now at the mercy of the availability and correct-ness (at the time of caching) of the external providers.
- Preferred extension for file is .appcache, however, browsers seem to be fine with anything.
- more in gotchas in get-offline, and here.
Some useful links for reading before you rip your hairs out:
Application Cache is a Douchebag
Taking your web sites and apps offline with the HTML5 appcache
Improving app cache
AppCache Wows, Vows & Woes
A Beginner's Guide to using the Application Cache
Debugging HTML 5 Offline Application Cache