Application Cache API ("AppCache")

Article
11/03/2017

Internet Explorer 10 and Windows apps using JavaScript support the Application Cache API (or AppCache), as defined in the HTML5 specification, which allows you to create offline web applications. AppCache enables webpages to cache (or save) resources locally, including images, script libraries, style sheets, and so on. In addition, AppCache allows URLs to be served from cached content using standard Uniform Resource Identifier (URI) notation.

By using AppCache to save resources locally, you improve the performance of a webpage by reducing the number of requests made to the hosting server; you also enable offline access to cached resources.

To cache resources locally:

1. Create a manifest file that defines the resources you want to save.

2. Reference the manifest file in each webpage designed to use cached resources.

Creating a manifest file

The manifest file is a text file that defines the caching behavior for resources used by the webpage, as shown in the following example.

CACHE MANIFEST

CACHE:
# Defines resources to be cached.
script/library.js
css/stylesheet.css
images/figure1.png

FALLBACK:
# Defines resources to be used if non-cached
# resources cannot be downloaded, for example
# when the browser is offline..
photos/ figure2.png

NETWORK:
# Defines resources that will not be cached.
figure3.png

Manifest files are divided into the following sections:

The CACHE: section defines resources that will be stored locally. In this example, three files are cached.
The FALLBACK: section defines resources to be used when other resources are not available. For example, this example defines figure2.png as a fallback image for the photos folder. If the browser cannot access images in the photos folder (because the browser is offline or because the server cannot be reached), figure2.png will replace the unavailable images in the rendered markup. As a result, figure2.png will be cached locally.
The NETWORK: section specifies resources to be accessed when there is a network connection. Resources in this section are not cached. This section allows the use of the wildcard (*) character to indicate that all other resources should not be cached.

Manifest files can contain any number of these sections and sections can be repeated; however, new sections must begin with the section header followed by a colon, as shown in the previous example. If no section header is provided, the CACHE: header is presumed. The following example shows a simplified manifest.

CACHE MANIFEST
script/library.js
css/stylesheet.css
images/figure1.png

In addition, manifest files:

Must be encoded with 8-bit Unicode Transformation Format (UTF-8) character encoding.
Must be served with a text/cache-manifest MIME type.
Must begin with the line "CACHE MANIFEST".
Can contain comments, preceded by the pound sign (#).

For more information, see the cache manifest syntax.

Declaring a manifest

To associate a manifest with a webpage, assign the name of the manifest file to the manifest attribute of the html element, as shown in the following example.

<!doctype html>
<html manifest="appcache.manifest">
 <head>
  <title>A Web Page</title>
  <script src="library.js"></script>
  <link rel="stylesheet" href="stylesheet.css">
 </head>
 <body onload="doSomething();">
  <p>Results go here: <span id="results">Unknown</span></p>
 </body>
</html>

In this example, the webpage declares "appcache.manifest" as the manifest file. The manifest declaration is interpreted like any other file reference. Because this example uses a relative file name, the manifest is presumed to be located in the same directory as the webpage itself.

Note File references in the manifest are interpreted with respect to the location of the manifest file, not the webpage that declares it.

It is not necessary for the manifest to include the name of the webpage declaring the manifest; webpages that declare manifests are cached automatically.

The ApplicationCache object

Internet Explorer 10 also supports the ApplicationCache object, which provides methods and properties that enable you to manage the application cache. In addition, you can define event handlers that show the progress of the cache process.

Use the applicationCache property of a window object (or worker object) to access the ApplicationCache object, as shown in the following example.

var sCacheStatus = "Not supported";
if (window.applicationCache) 
{
   var oAppCache = window.applicationCache;
   switch ( oAppCache.status ) 
   {
      case oAppCache.UNCACHED : 
         sCacheStatus = "Not cached"; 
         break;
      case oAppCache.IDLE : 
         sCacheStatus = "Idle"; 
         break;
      case oAppCache.CHECKING : 
         sCacheStatus = "Checking"; 
         break;
      case oAppCache.DOWNLOADING : 
         sCacheStatus = "Downloading"; 
         break;
      case oAppCache.UPDATEREADY : 
         sCacheStatus = "Update ready"; 
         break;
      case oAppCache.OBSOLETE : 
         sCacheStatus = "Obsolete"; 
         break;
      default : 
        sCacheStatus = "Unexpected Status ( " + 
                       oAppCache.status.toString() + ")";
        break;
   }
}
return sCacheStatus;

This example uses the status property to determine the status of the application cache for the document current loaded by the webpage.

The ApplicationCache object supports two methods for controlling the cache. The update method initiates an asynchronous check for updates, similar to the one performed when a webpage is first loaded. Any existing cache will be used until the webpage is reloaded or the swapCache method Is called. To begin using an updated cache, either reload the webpage (manually or programmatically) or call the swapCache method. Because the cache is updated when a webpage is reloaded, it is not necessary to call the swapCache method before reloading or refreshing a webpage.

Note The updated cache is not used by the webpage until it is reloaded, either manually by the user or programmatically using the reload method of the window.location object.

The ApplicationCache object supports the following events:

The cached event fires when the manifest has been cached.
The checking event fires when the presence of an update is being checked.
The downloading event fires when manifest resources are being downloaded.
The progress event fires while manifest resources are being downloaded.
The error event fires when a problem occurs, such as an HTML 404 or 410 response code. The event is also fired when the manifest file cannot be downloaded.
The updateready event fires when a newer version of the cache is available.
The noupdate event fires when an update has been request, but the manifest has not changed.
The obsolete event fires when the current cache is marked as obsolete.

The following example shows how to register event handlers for these events.

if (window.applicationCache) {
  var appCache = window.applicationCache;
   appCache.addEventListener('error', appCacheError, false);
   appCache.addEventListener('checking', checkingEvent, false);
   appCache.addEventListener('noupdate', noUpdateEvent, false);
   appCache.addEventListener('downloading', downloadingEvent, false);
   appCache.addEventListener('progress', progressEvent, false);
   appCache.addEventListener('updateready', updateReadyEvent, false);
   appCache.addEventListener('cached', cachedEvent, false);
}