Offline application cache is a way to store assets on the browser for use when the user is not connected to the internet. This API further breaks down any barriers between a native application and a web application, since it does away with the major characteristic that sets a web application apart from a native one—the need for a connection to the World Wide Web. Although the user will obviously still need to be connected to the network at some point, so the application can be downloaded initially; after that, the application can run completely from the user's cache.
Probably the main use case for offline application cache is when the user's connection is not stable, consistent, or simply not on every time the application is used. This is especially true with games, as the user may choose to play a certain online game some of the time, but offline later on. Similarly, if the game needs to connect to a backend server, in order to perform whatever task (such as to retrieve new game data), this can be done whenever the user is connected, the resources can be again cached locally, and the new data can be used again, if and when the user's connectivity becomes unavailable.
The backbone of the offline application cache API is the manifest file, which specifies to the browser which resources should be cached for offline use, which resources must never be cached, and what the browser should do when an attempt is made to connect to the server, but no connection is found.
The manifest file is served with the HTML file that the user requests, when loading your application. More specifically, the host HTML file specifies the path to the manifest file, which the browser then fetches and processes in parallel, with the download and processing of the main application. This is done with the manifest attribute in the root html tag.
<!doctype html> <html manifest="manifest.appcache">
Observe that the above snippet specifies a manifest file named manifest.appcache, located in the same directory as the HTML file specifying the manifest. The name of the file, along with its extension, is completely arbitrary. By convention, many developers named the manifest simply manifest.appcache, manifest (without an extension), or appcache.manifest. However, this file could very well be named manifest.php?id=2642, my-manifest-file.txt, or the_file.json.
An important thing to remember is that the manifest file be served with the proper MIME type. If the browser attempts to fetch whatever file is listed in the manifest attribute of the root HTML tag, and the MIME type is not text/cache-manifest, then the browser will reject the manifest, and no offline application cache will take place.
There are many ways to set the MIME type to a file, but generally this is a server setting. If using an Apache server, such as the one we are using with WAMP, MAMP, or LAMP (see the online chapter, Setting Up the Environment), we can easily do this with a .htaccess file. For example, in the root directory of our project, we can create a file named .htaccess containing the following code:
AddType text/cache-manifest .appcache
This would tell the server to add the right MIME type to any file with an extension of .appcache. Of course, if you decide to tweak the htaccess file to serve the cache-manifest MIME type to other file extensions, you could possibly run into issues if the extension you choose is already associated with other MIME types (such as .json).
The first line of the manifest file must be the following string:
CACHE MANIFEST
If this line isn't present again, the entire API will take no effect. If there is as much as an extra white space before the string listed above, the browser will throw the following error, indicating that the file manifest is invalid, and nothing will be cached:
Application Cache Error event: Failed to parse manifest
Note
When using offline application cache on your games, make sure to keep an open eye on your browser's JavaScript console. If anything goes wrong at all, such as finding the manifest file, parsing the manifest, or loading any of the resources described in the manifest, the browser will let you know that something went wrong by raising an exception, but it will go on. Unlike most fatal JavaScript exceptions, a fatal offline application cache exception doesn't stop or influence the execution of the script that initiated the caching process. Thus, you may be getting app cache exceptions and not know it, so get acquainted with whatever developer tools your browser supports, and make good of it.
The rest of the manifest can be divided into three main categories, namely, assets to be cached, assets to never be cached, and the fallback asset. Comments can be placed anywhere within the file, and are denoted by a pound sign. The entire line following a pound sign is ignored by the manifest parser.
CACHE MANIFEST # HTML5 Snake, Version 1.0.0 CACHE: index.html js/next-empty.worker.js js/renderer.class.js js/snake.class.js img/block-green.png img/fruit-01.png fonts/geo.woff fonts/vt323.woff css/style.css NETWORK: * FALLBACK: fallback.html
By using the wild card under the network section, we indicate that any resource not specified under cache, qualified under the network section, meaning that those resources are not to be cached. Any attempt to load those resources when network access is not available will result in the fallback file being loaded instead. This is a good option to let the user know that network access is needed without needing to special case any extra code.
Once the manifest is parsed and all the resources are cached, all of the resources will remain cached, until the user deletes the offline application cache data (or all of the data cached by the browser), or the manifest is changed. Even if only a single character changes in the manifest file, the browser will consider it to be an update, thus, all of the resources are cached anew. Because of this, many developers write a comment line right at the top of the manifest file that, among other optional things, they include some sort of version number that identifies a unique version of the manifest. This way, if one or more assets changes, we can force the browser to re-cache those assets by simply changing the version number listed in the manifest file. Remember, the browser will only check the text in the manifest file in order to determine if it needs to download new assets. If assets change (say, you update JavaScript code listed in the manifest, or some graphics, or any other resource), but the manifest text doesn't, those resources will not be pulled from the server, and the user will continue to use an outdated asset in his or her application, since the assets are loaded only from the cache.