Using the AppCache API



The AppCache API makes content and webpages available even when a web application is in offline mode. AppCache stores files in the application cache in the browser.

The amount of data the browser can store locally is limited for offline use. Two components make up the AppCache API: the manifest file and a JavaScript API.

Using AppCache manifest

Specifying that a page should be available for offline use is as easy as adding an attribute to the HTML element in the page.

The code below gives an example:

<html manifest="webApp.appcache">
    //page content
</html>

The manifest attribute tells the browser that this webpage needs to be available offline. The value of the manifest attribute points to a manifest file with .appcache extension.

The application cache manifest file must list each and every file and resource required to be stored for offline use. The browser downloads the manifest and stores it locally. It also downloads all the files listed in the manifest so that they are available offline.

The manifest file contains three sections:

  1. the CACHE section lists all the resources that must be cached offline including all CSS, JPG, video and audio files.
  2. the NETWORK section declares any resources that must be available from the Internet. These items can’t be cached. Anything that the page requires from the Internet must be listed here.
  3. the FALLBACK section provides fallback instructions to the browser in the event that an item isn’t available in the cache and the browser is in offline mode.

The code below is an axample of appCache manifest file:

     HTML FILE
    <html manifest="webApp.appcache">
        …
    </html>
    A typical manifest file looks like this:
    CACHE MANIFEST
    # My Web Application Cache Manifest
    # v.1.0.0.25
    #
    #Cache Section. All Cached items.
    
    CACHE
    /site.css
    /logo.gif
    /main.js
    /home/index.html
    /home/about.html
    #Required Network resources
    
    NETWORK:
    login.html
    #Fallback items.
    
    FALLBACK:
    login.html fallback-login.html

Using the JavaScript AppCache API

As with Web Storage, the application cache is available in JavaScript as a global object. The following code gets a reference to the AppCache global object:

var appCache = window.applicationCache;

When application cache makes pages available offline you can verify its status by evaluating the status property of the AppCache object.

The status property could be one of the values listed in the Table:

Status Description
Uncached The web application isn’t associated with an application manifest.
Idle The caching activity is idle, and the most up-to-date copy of the cache is being used.
Checking The application manifest is being checked for updates.
Downloading The resources in the application manifest are being downloaded.
UpdateReady The resources listed in the manifest have been successfully downloaded.
Obsolete The manifest can no longer be downloaded, so the application cache is being deleted.

After you know the cache status, two methods on the AppCache object can be useful. The methods are listed in the following Table:

Method Description
swapCache Indicates that the cache be replaced with a newer version.
update Tells the browser to update the cache if an update is available.

In addition to the properties and methods, the AppCache object can raise a series of events that you can handle. Handling some of the events and forcing an update can be useful.

The following Table lists the available events:

Event Description
onchecking The browser is checking for an update to the application manifest, or the application is being cached for the first time.
onnoupdate The application manifest has no update available.
ondownloading The browser is downloading what it has been told to do per the manifest file.
onprogress Files are being downloaded to the offline cache. This event fires periodically to report progress.
oncached The download of the cache has completed.
onupdateready The resources listed in the manifest have been newly redownloaded, and the swapCache method might be called.
onobsolete A manifest file is no longer available.
onerror An error has occurred. This could result from many things. Appropriate logging is necessary to get the information and resolve.

The most common scenario is to handle the onupdateready method and then make a call to the swapCache method.

The code below demostrates this:

<script type="text/javascript">
    window.onload = function () {
        var appCache = window.applicationCache;
        appCache.oncached = function (e) { alert("cache successfully downloaded."); };
        appCache.onupdateready = function (e) { appCache.swapCache(); };
    }
</script>

It’s important that you’re aware the API is available when you need to receive timely information about the process, such as by handling the onprogress event.


PROMOTIONS