Beginning in iPhone OS 2.1 and Safari 4.0, Safari provides an offline application cache. This cache allows you to create web-based applications that work correctly even when the user’s computer or web-enabled device is not connected to the Internet.
This technology consists of two parts: a manifest file and JavaScript interfaces.
The manifest file is a text file that contains a list of resources to be cached.
The JavaScript programming interfaces allow you to trigger an update of the cached files when desired.
The manifest file specifies the resources—such as HTML, JavaScript, CSS, and image files —to downloaded and store in the application cache. After the first time a webpage is loaded, the resources specified in the manifest file are obtained from the application cache, not the web server.
The manifest file has the following attributes:
It must be served with type text/cache-manifest.
The first line must contain the text CACHE MANIFEST.
Subsequent lines may contain URLs for each resource to cache or comments.
Comments must be on a single line and preceded by the # character.
The URLs are file paths to resources you want to download and cache locally. The file paths should be relative to the location of the manifest file—similar to file paths used in CSS—or absolute.
The manifest must also declare a whitelist that contains a prefix match for all external resources that it needs to access when online. This whitelist begins with the identifier NETWORK: on a line by itself.
You can declare additional cache entries after network entries by inserting the identifier CACHE: on a line by itself, if desired.
The manifest may, if desired, contain fallback sections. These sections begin with the identifier FALLBACK: and contain a series of lines containing two URIs. The second URI is a URI that the browser should use if the first URI is inaccessible. The URIs must both be from the same origin as the manifest itself. Both URIs may be partial URIs (prefixes).
For example:
FALLBACK: |
/files/projects /projects |
In the above example, if a file cannot be found in /files/projects, the client tries again, replacing /files/projects with /projects.
The HTML file that declares the manifest file, described in “Declaring a Manifest File,” is automatically included in the application cache. You do not need to add it to the manifest file.
For example, “Creating the index.html File” shows a manifest file that contains URLs to some image resources.
Listing 1-1 Sample manifest file
CACHE MANIFEST |
# This is a comment. |
# Cache manifest version 0.0.1 |
# If you change the version number in this comment, |
# the cache manifest is no longer byte-for-byte |
# identical. |
demoimages/clownfish.jpg |
demoimages/clownfishsmall.jpg |
demoimages/flowingrock.jpg |
demoimages/flowingrocksmall.jpg |
demoimages/stones.jpg |
NETWORK: |
# All URLs that start with the following lines |
# are whitelisted. |
http://example.com/examplepath/ |
http://www.example.org/otherexamplepath/ |
CACHE: |
# Additional items to cache. |
demoimages/stonessmall.jpg |
FALLBACK: |
demoimages/ images/ |
After you create a manifest file you need to declare it in the HTML file. You do this by adding a manifest attribute to the <html> tag as follows:
<html manifest="demo.manifest"> |
The argument to the manifest attribute is a relative or absolute path to the manifest file.
Important: In some browsers, the application cache does not work fully if you use a non-HTML 5 DOCTYPE declaration. Instead, use an HTML 5 DOCTYPE declaration:
<!DOCTYPE html> |
In most cases, creating a manifest file and declaring it is all you need to do to create an application cache. After doing this, the resources are automatically stored in the cache the first time the webpage is displayed and loaded from the cache by multiple browser sessions thereafter. Read the following sections if you want to manipulate this cache from JavaScript.
You can wait for the application cache to update automatically or manually trigger an update using JavaScript. The application cache automatically updates only if the manifest file changes. It does not automatically update if resources listed in the manifest file change.
The manifest file is considered unchanged if it is byte-for-byte identical to the previous version; changing the modification date of a manifest file does not trigger an update. You must change the contents of the manifest file. (Changing a comment is sufficient.)
Note that errors can also occur when updating the application cache. If downloading the manifest file or a resource specified in the manifest file fails, the entire update process fails. If the update process fails, the current application cache is not corrupted—the browser continues to use the previous version of the application cache. If the update is successful, webpages begin using the new cache when they reload.
Use the following JavaScript class to trigger an update to the application cache and check its status. There is one application cache per document represented by an instance of the DOMApplicationCache class. The application cache is a property of the DOMWindow object.
For example, you get the DOMApplicationCache object as follows:
cache = window.applicationCache; |
You can check the status of the application cache as follows:
if (window.applicationCache.status == window.applicationCache.UPDATEREADY)... |
If the application cache is in the UPDATEREADY state, then you can update it by sending it the update() message as follows:
window.applicationCache.update(); |
If the update is successful, swap the old and new caches as follows:
window.applicationCache.swapCache(); |
The cache is ready to use when it returns to the UPDATEREADY state. See the documentation for DOMApplicationCache for other status values. Again, only webpages loaded after an update use the new cache, not webpages that are currently displayed by the browser.
Note: Using JavaScript to add and remove resources from the application cache is currently not supported.
You can also listen for application cache events using JavaScript. Events are sent when the status of the application cache changes or the update process fails. You can register for these events and take the appropriate action.
For example, register for the updateready event to be notified when the application cache is ready to be updated. Also, register for the error event to take some action if the update process fails—for example, log an error message using the console.
cache = window.applicationCache; |
cache.addEventListener('updateready', cacheUpdatereadyListener, false); |
cache.addEventListener('error', cacheErrorListener, false); |
See the documentation for DOMApplicationCache for a complete list of event types.
Last updated: 2010-01-20