Using the Application Cache

Redirected from en/Offline resources in Firefox

Table of contents

  1. 1. The application cache
    1. 1.1. How the application cache works
      1. 1.1.1. Cache states
    2. 1.2. Resources in the application cache
      1. 1.2.1. Master entries
      2. 1.2.2. Fallback entries
      3. 1.2.3. Network entries
  2. 2. The cache manifest
      1. 2.1.1. A sample cache manifest
  3. 3. Specifying a cache manifest
  4. 4. The update process
  5. 5. Testing for updates
  6. 6. Gotchas
  7. 7. Storage location and clearing the offline cache
  8. 8. Browser Compatibility
  9. 9. See also
Page Notifications Off

HTML5 supports offline caching of web applications' resources; files are stored in an application cache—a collection of resources obtained from  a cache manifest file (*.appcache) included in the web application.

The application cache

Each web application's resource manifest has its own application cache. Since applications can share resources (and even the same manifest URI), each application's cache has a separate copy of all the resources. These caches are versioned; each time the web application is visited while online, a new version of the application may be synced into the application cache if updates are available. That new version will then be used on the next visit to the site.

How the application cache works

The application cache modifies the normal process of loading a document; if an application cache already exists, resources are loaded directly from that cache, without accessing the network, speeding up the page load. The web application then checks if the manifest has been updated on the server and if it has, a new version of the cache is downloaded. This is done in the background and doesn't affect performance significantly. 

Application caches can also become obsolete. If the manifest is removed from the server, the browser removes all application caches that use that manifest, then sends an "obsoleted" event to the application cache object. Then the application cache's status is set to OBSOLETE.

Cache states

Each application cache has a state, which indicates the current condition of the cache.  Caches that share the same manifest URI share the same cache state, which will be one of the following:

UNCACHED
A special value that indicates that an application cache object is not fully initialized.
IDLE
The application cache is not currently in the process of being updated.
CHECKING
The manifest is being fetched and checked for updates.
DOWNLOADING
Resources are being downloaded to be added to the cache, due to a changed resource manifest.
UPDATEREADY
There is a new version of the application cache available.  There is a corresponding updateready event, which is fired instead of the cached event when a new update has been downloaded but not yet activated using the swapCache() method.
OBSOLETE
The application cache group is now obsolete.

Resources in the application cache

Resources in the application cache are specified by a URI pointing to a manifest file (a file with the *.appcache extension).  This file is referenced in the html element's manifest attribute. A manifest is downloaded and processed during the application cache update process. Entries must have the same scheme, host, and port as the manifest. The cache always includes at least one resource, identified by URI. All resources fit into one of the following categories:

Master entries
These are resources added to the cache because a browsing context visited by the user included a document that indicated that it was in this cache using its manifest attribute.
Explicit entries
These are resources listed in the cache's manifest.
Fallback entries
These are resources listed in the cache's manifest as fallback entries. New in Firefox 3.5
Note: Resources can be tagged with multiple categories, and can therefore be categorized as multiple entries.  For example, an entry can be both an explicit entry and a fallback entry.

Master entries

Master entries are any HTML files that include a manifest attribute in their <html> element.  For example, let's say we have the HTML file http://www.example.com/entry.html, which looks like this:

<html manifest="example.appcache">
  <h1>Application Cache Example</h1>
</html>

If entry.html is not included in the manifest, visiting the entry.html page causes entry.html to be added to the application cache as a master entry.

Fallback entries

Fallback entries are used when an attempt to load a resource fails.  For example, imagine that there is a cache manifest located at http://www.example.com/example.appcache, with the following contents:

CACHE MANIFEST
FALLBACK:
example/bar/ example.html

Any request to http://www.example.com/example/bar/ or any of its subdirectories and their contents will cause a network request to attempt to load the requested resource.  If the attempt fails, either due to a network failure or a server error of some kind, the contents of the file example.html are loaded instead.

Network entries

Entries listed under NETWORK: may contain zero or more resources that the web application requires online access for. It is, essentially, an "online whitelist." URIs specified in the NETWORK section are loaded from the server instead of the cache. This lets the browser's security model protect the user from potential security breaches by limiting access only to approved resources.

Note: The online whitelist is ignored in versions of Firefox prior to 3.5.

You can use this to, for example, load and execute scripts and other code from the server instead of the cache:

CACHE MANIFEST
NETWORK:
/api

This ensures that requests to load resources contained in the http://www.example.com/api/ subtree will always go to the network without attempting to access the cache.

Note: Simply omitting master entries (files that have the manifest attribute set in the html element) from the manifest file would not have the same result, because master entries will be added—and subsequently served from—the application cache. 

The cache manifest

Cache manifest files must be served with the text/cache-manifest MIME type, and all resources served using this MIME type must follow the syntax for an application cache manifest, as defined here. Cache manifests are UTF-8 format text files and may, optionally, include a BOM character. Newlines may be represented by line feed (U+000A), carriage return (U+000D), or carriage return and line feed both.

The first line of the cache manifest must consist of the string CACHE MANIFEST (with a single U+0020 space between the two words), followed by zero or more space or tab characters. Any other text on the line will be ignored.

The remainder of the cache manifest must be comprised of zero or more of the following lines:

Blank line
You may use blank lines comprised of zero or more space and tab characters.
Comment
Comments consist of zero or more tabs or spaces followed by a single # character, followed by zero or more characters of comment text. Comments may only be used on their own lines, and cannot be appended to other lines. This also means that you cannot specify fragment identifiers.
Section header
Section headers specify which section of the cache manifest is being manipulated. There are three possible section headers:
Section header Description
CACHE: Switches to the explicit section. This is the default section.
FALLBACK: Switches to the fallback section.

Firefox 3.5 note

The fallback section is ignored by versions of Firefox prior to 3.5.
NETWORK: Switches to the online whitelist section.

Firefox 3.5 note

The online whitelist section is ignored by versions of Firefox prior to 3.5.
The section header line may include whitespaces, but must include the colon (:) in the section name.
Section data
The format for lines of data varies from section to section. In the explicit (CACHE:) section, each line is a valid URI or IRI reference to a resource to cache (no wildcard characters are allowed in this sections). Whitespace is allowed before and after the URI or IRI on each line. In the Fallback section each line is a valid URI or IRI reference to a resource, followed by a fallback resource that is to be served up when a connection with the server cannot be made. In the network section, each line is a a valid URI or IRI reference to a resource to fetch from the network (the wildcard * is allowed in this section).

Cache manifests may switch back and forth from section to section at will (each section header can be used more than once), and sections are allowed to be empty.

Note: Relative URIs are relative to the cache manifest's URI, not to the URI of the document referencing the manifest.

A sample cache manifest

The following is a simple cache manifest example.appcache for an imaginary web site at www.example.com.

CACHE MANIFEST
# v1 - 2011-08-13
# This is a comment.
http://www.example.com/index.html
http://www.example.com/header.png
http://www.example.com/blah/blah

In this example, thee is no section header, so all data lines are assumed to be in the explicit (CACHE:) section. You can also specify relative URLs (index.html, etc.)

The "v1" comment is there for a good reason. Because the cache is only updated when the manifest changes, byte for byte. If you change the resources (for example, updating the header.png image with new content), you need to change the manifest file contents in order to let the browser know that it needs to refresh the cache (and since header.png is already in the manifest file, you need to change something else). You can do this by any change to the manifest, but having a version number is the recommended best practice.

Important: Do not specify the manifest itself in the cache manifest file otherwise it will be nearly impossible to inform the browser a new manifest is available.

The following is a more complete cache manifest for the same, imaginary web site at www.example.com. This example also uses the FALLBACK and NETWORK sections to specify that the network.html page must always be retrieved from the network and that the fallback.html page should be served as a fallback resource. For example, in case a connection to the server cannot be established.

CACHE MANIFEST
# v1 2011-08-14
# This is another comment
index.html
cache.html
style.css
image1.png

# Fallback content
FALLBACK:
/ fallback.html

# Use from network if available
NETWORK:
network.html

 

Specifying a cache manifest

To use application cache, you need to use the manifest attribute in the html element as shown in the following example:

<html manifest="example.appcache"> 
  ...
</html>

Some browsers like Firefox will display a notification bar the first time the user loads your application saying "This website (www.example.com) is asking to store data on your computer for offline use. [Allow] [Never for This Site] [Not Now]". The term "Offline(-enabled) applications" sometimes refers specifically to applications allowed by the user to use the offline capabilities.

The update process

  1. When the browser visits a document that includes a manifest attribute and if no application cache exists yet, it will load the document and then fetch all the entries listed in the manifest file, creating the first version of the application cache. 
  2. Subsequent visits to that document will trigger the browser to load the document and other assets specified in the manifest file from the application cache (not from the server) and in addition the browser will also send a checking event to the window.applicationCache object, then fetches the manifest file, following the appropriate HTTP caching rules. If the currently-cached copy of the manifest is up-to-date, the noupdate event is sent to the applicationCache, and the update process is complete. (This is why if you change any resources on the server, you need to also change the manifest file so the browser knows it needs to fetch all the resources again.
  3. If the manifest file has changed, all files in the manifest—as well as those added to the cache by calling applicationCache.add()—are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into this temporary cache, a progress event is sent to the applicationCache object. If any errors occur, an error event is sent, and the update halts.
  4. Once all the files have been successfully retrieved, they are moved into the real offline cache atomically, and a cached event is sent to the applicationCache object. Since the document has already been loaded into the browser from the cache, the updated document won't be rendered until the document is reloaded (either manually or programatically).

Testing for updates

Testing to see if an application has an updated cache manifest available can be done programmatically through Javascript. Since the cache may have been updated before any script using events to test for updates, scripts should always test window.applicationCache.status.

reference to undefined name 'syntax' Exception of type 'MindTouch.Deki.Script.Runtime.DekiScriptUndefinedNameException' was thrown. (click for details)

 To manually start testing for a new manifest you can use window.applicationCache.update().

Gotchas

  • Since applications are using a cache, simply updating the files served under web pages is not enough to update files that have been cached. Updating the manifest will be required before the files are using their new source. This can be done programmatically through window.applicationCache.swapCache(), but already loaded resources will not be affected. In order to ensure resources are loaded from new version of the application cache refreshing the page is ideal.
  • it is a good idea to set expires headers on your web server for *.appcache files to expire immediately to avoid the risk of caching the manifest files. For example, in Apache you can configure this as follows:
    ExpiresByType text/cache-manifest "access plus 0 seconds"

Storage location and clearing the offline cache

In Chrome you can clear the offline cache by selecting "Clear browsing data..." in the preferences or by visiting chrome://appcache-internals/. Safari has a similar "Empty cache" setting in its preferences but a browser restart may also be required.

In Firefox, the offline cache data is stored separately from the Firefox profile—next to the regular disk cache:

  • Windows Vista/7: C:\Users\<username>\AppData\Local\Mozilla\Firefox\Profiles\<salt>.<profile name>\OfflineCache
  • Mac/Linux: /Users/<username>/Library/Caches/Firefox/Profiles/<salt>.<profile name>/OfflineCache

In Firefox the current status of the offline cache can be inspected on the about:cache page (under the "Offline cache device" heading).

The offline cache is not cleared via Tools -> Clear Recent History (bug 538595)
The offline cache is not cleared via Tools -> Options -> Advanced -> Network -> Offline data -> Clear Now (bug 538588).
The offline cache can be cleared for each site separately using the "Remove..." button in Tools -> Options -> Advanced -> Network -> Offline data.

See also clearing the DOM Storage data.

Browser Compatibility

  • Desktop
  • Mobile

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 4.0 3.5 10.0 10.6 4.0
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 2.1 ? -- 11.0 3.2

 

Tags (3)

Edit tags

Attachments (0)

 

Attach file