HTML & CSS
Article

Common Pitfalls to Avoid when using HTML5 Application Cache

By Tanay Pant

Application Cache, also known as AppCache, has been a pretty hot topic with web developers these days. AppCache enables you to allow your website visitors to browse your website when they are offline. You can even store parts of your website, such as images, stylesheets, or web-fonts in the cache on a user’s computer. This can help your website load faster and hence reduces load on your server.

To use AppCache, you make a manifest file with a file extension of “appcache”, for example: manifest.appcache. In this file you can list all the files you want to be cached. To enable it on your site, you have to include the reference to this manifest file on your webpage on the html element, like this:

<html lang="en" manifest="manifest.appcache">

Here’s a sample manifest file:

CACHE MANIFEST
# 23-01-2015 v0.1
/style.css
/logo.gif
/script.js

NETWORK:
*

FALLBACK:
/server/ /fallback.html

Along with the benefits of AppCache, there are some common pitfalls that you should avoid in order to prevent ruining the user experience and breaking your application.

Never list the Manifest File in the Manifest File

If you include the manifest file itself in the application cache manifest, it gets in a kind of loop, making it nearly impossible to inform your website that a new cache file is available and it should download and use the new manifest file instead of the old one. Therefore, always be careful not to make the following mistake:

CACHE MANIFEST
# 23-01-2015 v0.1

manifest.appcache
page2.css

Non-Cached Resources Do Not Load On a Cached Page

This is a very common mistake when working with AppCache for the first time. This is where the NETWORK flag in the manifest file comes to the rescue. The NETWORK section of a manifest file specifies resources for which a web app requires online access.

URLs specified under the NETWORK flag are basically “whitelisted”, that is the files specified under this flag are always loaded from the server when an internet connection is available. For example, the following snippet of code makes sure that requests to load resources contained in the /api/ subtree always load from the network and not the cache.

NETWORK:

/api

Always Set Application Type Manifest in .htaccess of Your Server

A manifest file should always be served under the correct media type of text/cache-manifest. If the media type is not set, then AppCache will not work.

It should always be configured in the .htaccessof your production server. This point is mentioned in most tutorials teaching AppCache but is overlooked by many developers when they are transitioning their web application from a development to a production server.

Enter the following in your .htaccess file in Apache:

AddType text/cache-manifest .manifest

If you are uploading your application to Google App Engine, you can accomplish the same task by adding the following piece of code to your app.yaml file:

- url: /public_html/(.*\.appcache)
  static_files: public_html/\1
  mime_type: text/cache-manifest
  upload: public_html/(.*\.appcache)

Avoid Dropping the Whole Manifest Due to File Not Found

If even a single file specified in the manifest file is not found or is not able to be downloaded, then the whole manifest file is dropped. This is a strange behavior of AppCache and should be kept in mind while designing a web application making use of AppCache.

For example:

CACHE MANIFEST
# 23-01-2015 v0.1
/style.css
/logo.gif
/script.js

If logo.gif was deleted, the AppCache will not be able to find the deleted image file and hence nothing in the manifest file will be executed.

Data is Loaded from AppCache Even When Online

Once the cache manifest file has been saved by your web browser, the files are loaded from the cache manifest itself, even if the user is connected to the internet. This feature helps in improving the loading speed of your website and helps in reducing server loads.

Changes on the Server Do Not Take Place Until the Manifest File’s Updated

Since you know from the previous point that data is loaded from AppCache even if the user are online, changes that you have made to the files in your website or server do not take place until the manifest file is updated.

You always have to update the manifest file after updating the website or your user will never be able to see the changes, but they will only see the previously cached data. You can update the version number or date in a comment in your manifest file to force the user’s web browser to download the new version of the manifest file. For instance, if the following used to be your manifest file before making the changes to your website:

CACHE MANIFEST
# 23-01-2015 v0.1

It could be changed to something like the below block of code, so that the user’s browser could download a new copy of the manifest file.

CACHE MANIFEST
# 23-01-2015 v0.2

Please note that line preceded by # is a comment line that isn’t executed.

The Manifest File Must be Served from Same Origin as Host

Although manifest files can hold reference to resources to be cached from other domains, it should be served to the web browser from the same origin as the host page. If this is not the case, then the manifest file will fail to load. For example the following manifest file is correct:

CACHE MANIFEST
# 23-01-2015 v0.2

https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.js

Here we have specified the content to be stored in the user’s browser cache which is referenced from another domain, which is perfectly fine.

Relative URLs Are Relative to the Manifest’s URL

One important thing to take note of is that the relative URLs that you mention in the manifest are relative to the manifest file and not to the document where you reference the manifest file. If you make this error when the manifest and the reference are not in the same path, the resources will fail to load and in turn the manifest file will not be loaded.

If your application structure looks like the following:

css/style.css
js/main.js
img.jpg
index.html
manifest.appcache

Then your manifest file should look like:

CACHE MANIFEST
# 23-01-2015 v0.2

css/style.css
js/main.js
img.jpg

Programmatically Checking the Status of Your Manifest

You can programmatically check if your application is using an updated version of the cache manifest by testing window.applicationCache.status. Here’s some example code:

function onUpdateReady() {
  alert('found new version!');
}

window.applicationCache.addEventListener('updateready', onUpdateReady);

if (window.applicationCache.status === window.applicationCache.UPDATEREADY) {
  onUpdateReady();
}

Running the above code on a website lets you know when a new update for the AppCache manifest is available. Please note that UPDATEREADY is a defined state. You can even use the swapCache() method in the onUpdateReady() function to swap the older manifest file with the newer one:

window.applicationCache.swapCache();

Conclusion

AppCache is a useful technology, but as we’ve seen, you should be careful when implementing it in your projects. Developers should be selective in selecting what we should include in our manifest file. Ideally, the manifest file should include static content such as stylesheets, scripts, web-fonts and images. However, you are always the best judge of what to include in your manifest file. Appcache is a double edged sword, so be careful while using it!

Much of what’s discussed above has been covered elsewhere, along with some additional points. You can check out the following resources for more:

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Get the latest in Front-end, once a week, for free.