HTML5 Application caches: Storing Application Resources

This tutorial demonstrates how you can use HTML5 application caches.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the HTML5 Application caches API basics by learning about:

Setting the Cache Manifest
Compose the manifest file to activate application caching.
Updating the Cache
Control application cache updates.
Managing the Cache Events
Check the cache status and manage events based on it.

Setting the Cache Manifest

To enable application caches, you must learn to set the cache manifest file:

Begin the manifest file with CACHE MANIFEST content:

CACHE MANIFEST
# 2013-03-18 v2.0.0
images/sound-icon.png 
images/background.png
/tizen_application_cache.html
/main.js

Note
The # 2013-03-18 v2.0.0 line is used for searching. When the content in an image or file list is changed, it does not automatically update the cache. It is updated if the manifest file is changed. Even if the content in the description is changed, cache update is possible.

Define the files to be cached in the CACHE section:
```
CACHE:
style/default.css
```
This is the default section for entries. Files listed under this header are explicitly cached after they are downloaded for the first time.

Note

CACHE section can be omitted, if automatic cache save is used.
Define the online white list in the NETWORK section:
```
NETWORK:
comm.cgi
login.asp
```
All requests to these resources bypass the cache, even if the user if offline. Wild cards like '*' can be used.
Define the fallback pages in the FALLBACK section:
```
FALLBACK:
/ tizen  /tizen_offline.html
```
This section is optional and used to specify fallback pages in case a resource is inaccessible. In the example above, if the file in the /tizen folder cannot be loaded in an offline state, it is replaced with the tizen_offline.html file.

Note
CACHE section can be omitted, if automatic cache save is used.

Note
The cached version of the file is displayed to the user even when an updated file is uploaded to the server. If the file is updated, the manifest file must be changed accordingly. The cache size in a mobile or desktop Web browser is normally set as 5 MB per domain.

Updating the Cache

To enable application caches in your application, you must learn to update the cache:

Include the manifest property in the <html> tag to enable loading the manifest file and caching content by the browser:
```
<!DOCTYPE html>
<html manifest="clock.appcache">
```
If the content of the cache_test.js file is changed and updating the cache is necessary, edit the manifest file accordingly:
```
CACHE MANIFEST
#VERSION 1.0.0
CACHE:
cache_test.js
```

Reconnect and check whether there are edited items in the manifest file using the update() method:

<script>
   var update = function() 
   {
      var appCache = window.applicationCache;
      appCache.addEventListener('updateready', handleCacheEvent, false);
      appCache.update();

If there are changes in the manifest file, use the swapCache() and handleCacheEvent() methods to update the cache:

      function handleCacheEvent(e) 
      {
         if (appCache.status == appCache.UPDATEREADY) 
         {
            try 
            {
               window.applicationCache.swapCache();
               document.getElementById('log').innerHTML = "Update is successful";
            }
         }
      }
   };
</script>

Note
The files used in this example are Web server source files. A change in the client cache occurs when the server file changes.

Source Code

For the complete source code related to this use case, see the following file:

appcache_update.html

Managing the Cache Events

To enable application caches in your application, you must learn to check the current status of the cache:

Check the window.applicationCache.status value:

<script>
   var appCache = window.applicationCache;
    
   switch (appCache.status) 
   {
      case 0: /* ApplicationCache.status is UNCACHED */
         break;
      case 1: /* ApplicationCache.status is IDLE */
         break;
      case 2: /* ApplicationCache.status is CHECKING */
         break;
      case 3: /* ApplicationCache.status is DOWNLOADING */
         break;
      case 4: /* ApplicationCache.status is UPDATEREADY */
         break;
      case 5: /* ApplicationCache.status is OBSOLETE */
         break;
      default: break;
   }
</script>

Different events can occur based on the cache status. Use the addEventListener method to add listeners in order to detect events:

<script>
   var appCache = window.applicationCache;
   appCache.addEventListener('cached', function()
   {
      /* Cached resource is downloaded */
   }, false);

   appCache.addEventListener('checking', function()
   {
      /* Manifest file is downloaded for the first time or if there is an update in the manifest */
   }, false);

   appCache.addEventListener('downloading', function()
   {
      /* Content is being updated */
   }, false);

   appCache.addEventListener('error', function()
   {
      /* Error occurred */ 
   }, false);

   appCache.addEventListener('noupdate', function()
   {
      /* No update is available */
   }, false);

   appCache.addEventListener('obsolete', function()
   {
      /* Manifest file cannot be found */
   }, false);

   appCache.addEventListener('progress', function()
   {
      /* Cache file is being downloaded */
   }, false);

   appCache.addEventListener('updateready', function()
   {
      /* All resources for update are downloaded */ 
   }, false);
</script>