2012/06/20
It is possible to interact with the Application Cache using the JavaScript API. This API can be accessed via window.applicationCache.
The API supports the following eventhandlers:- window.applicationCache.onchecking - This eventhandler is called when the browser is downloading the manifest file for the first time or when it is downloading the manifest to check whether there has been an update. This eventhandler is always the first eventhandler that is called.
- window.applicationCache.onnoupdate - This eventhandler is called, after the checking eventhandler is called, if there has been no change to the manifest file. No more eventhandlers are called after this eventhandler.
- window.applicationCache.ondownloading - This eventhandler is called, after the checking eventhandler is called, if the resources listed in the manifest file are being downloaded because either they have never been downloaded before or the manifest file was updated.
- window.applicationCache.onprogress - This eventhandler is called after each file listed in the manifest file is downloaded. The event passed to this eventhandler is a ProgressEvent with addition properties total and loaded however this are not reliably implemented in all browser.
- window.applicationCache.oncached - This eventhandler is called, after the downloading eventhandler is called, when all the resources in the manifest file have been downloaded. No more eventhandlers are called after this eventhandler.
- window.applicationCache.onupdateready - This eventhandler is called, after the downloading eventhandler is called, when there has been an updated to an existing Application Cache and all the resources in the manifest file have been downloaded. No more eventhandlers are called after this eventhandler.
- window.applicationCache.onobselete - This eventhandler is called if the request for the manifest file returns a 404 Not Found or a 410 Gone status code. It is used to indicate that the manifest file cannot be found and the Application Cache will be deleted. No more eventhandlers are called after this eventhandler.
- window.applicationCache.onerror - This eventhandler is called when there has been an error. There are a number of causes for this event including: an error while retrieving the manifest file, an error while retrieving resources listed in the manifest file, the manifest file was updated while the Application Cache was being updated. No more eventhandlers are called after this eventhandler.
- window.applicationCache.status - This indicates the current status value as an integer which can be decoded using any of the status constants (listed below).
- window.applicationCache.UNCACHED - The status for a page that does not use the Application Cache.
- window.applicationCache.IDLE - The status when the Application Cache is idle
- window.applicationCache.CHECKING - The status when the browser is downloading the manifest file for the first time or when it is downloading the manifest to check whether there has been an update.
- window.applicationCache.DOWNLOADING - The status when the resources listed in the manifest file are being downloaded because either they have never been downloaded before or the manifest file was updated.
- window.applicationCache.UPDATEREADY - The status when there has been an updated to an existing Application Cache and all the resources in the manifest file have been downloaded.
- window.applicationCache.OBSOLETE - The status when the request for the manifest file returns a 404 Not Found or a 410 Gone status code.
- window.applicationCache.update - This method triggers the process that requests the manifest file to check if it has been updated and then updates the Application Cache if required.
- window.applicationCache.swapCache - This method swaps the old cache, typically used to display the current page, with a new cache, typically updated due to a change in the manifest file.
One of the most useful ways to use the Application Cache API is to prompt the user to update the page when the Application Cache has been updated. This helps to resolve one of the know problem with using the Application Cache called the Double Refresh Issue, this is described in detail in my next blog Problems with Application Cache. The code to do this is as follows:
An alternative less "friendly" approach is to forcibly refresh the page if the Application Cache is updated, however this may result in the page appear to reload twice when ever the manifest is updated. The page would initially load immediately as the file are loaded from the Application Cache then it would be refreshed when the Application Cache is updated. For fast network this would possible be acceptable but for mobile network this would not produce a good experience. The code for such an approach would be:
Another use of the API can be to run an hourly poller that checks if the Application Manifest has been updated if used in addition with the code above that prompts the users to refresh the page this code would ensure that the users always has the latest copy of the site.
