In issue #350 of A List Apart Jake Archibald writes a great article about the HTML AppCache. Yes, the article is long. Your reptile brain will scream

TO LONG! WATCH YOUTUBE VIDEOS INSTEAD!!

but don’t listen to it. If you do any kind of web development, you should read the article. AppCache can really be great for certain things bit, as Jake will show you, it’s so full of caveats and weird behavior that you might be discouraged from using it.

The ApplicationCache spec is like an onion: it has many many layers, and as you peel through them you’ll be reduced to tears.¹

For an older version of this blog’s theme, I tried to use AppCache to increase download speed of a few assets, fonts in particular. It turns out, ”the road to hell is paved with good intentions”. The end result was a whole lot of pain when I updated the theme and a giant bag of hurt when I tried to switch it to the one currently in use. On my computer it looked fine, but on my iPad a broken version of the old theme was still in use and no matter how many times I’d hit the ”update” button in the browser, nothing would happen.

Ever since I finally figured what caused all the pain I’ve been meaning to write a blog post about it, but I’ve kept pushing it in front of me. Archibald’s article made me sick of my own postponement, so here is the short version of why AppCache together with WordPress makes for a giant pile of hurt.²

The problem of using AppCache with WordPress

Remember Gotcha #1: When the user visits a page a second time they’ll get the ApplicationCached version. If you’ve changed the url to the manifest, bad luck, the user’s cached version still points at the old manifest, which is obviously byte-for-byte the same so nothing updates, ever.³

When you (in this case me) develop a WordPress theme, you usually put all its files in wp-content/themes/[theme_name]. Logically, this is also where you’d put the AppCache Manifest file.

THIS IS A BAD IDEA!

Sorry, I didn’t mean to scream at you, it’s just all the frustration built up inside of me from actually making this mistake.

If you put an AppCache Manifest in your regular theme folder, this is what will happen.

1. A user will visit your site. Her/his browser will see the cache manifest, download it and cache everything according to it.
2. The user makes another visit some other day. Unless the manifest file itself has changed or been deleted, nothing will happen. If it has changed or been deleted, new assets will be downloaded according to it, but they will not be displayed until the next time the user visits.

So far nothing seems problematic. However, some day you will decide to switch theme. You’re assumption will be (at least mine was) that the user will once again visit you, her/his browser will download the new theme in the background and on the next visit the new theme will be showed in all its glory. There is just on problem…

The manifest file is still present in its old location, and remains unchanged.

This means that regardless of how many times you, or the visitor, hits update in the browser, the old cached version of the blog will show up. The best solution is to delete the old theme, or at least the old themes cache manifest. That way, things will go as you originally planned; the visitors browser will stop showing the old theme on the next visit.

So as you can see, things can quickly get out of hand with AppCache. Don’t use it in your WordPress themes without thorough testing. And read the A List Apart Article.