Imgcache Plugin to store images offline for Cordova Applications

Introduction

• Image Cache is JS library used to provide a nice interface for
  locally storing images for offline apps using PhoneGap/Cordova.
• This library is especially useful for mobile web applications using
  Phonegap/Cordova where image becomes stale (invalid) after normal offline navigation.
  therefore in this case we can not relied upon Normal Cache.
• So by using image cache we can store images in the cache and replace the stale version of normal cache
  with fresh version of image cache.
• This is the best solution I have found so far to provide easy caching
  of images within a Cordova web app while storing 10 to 15 images when you can not get rid of offline navigation.

Using imgcache.js

Installation

To start to use this library, import js/imgcache.js within your html file:

<script src="js/imgcache.js"></script>

Using with PhoneGap/Cordova: see [CORDOVA.md.][1]

Using as AMD / CommonJS modules

To use this library with AMD:

define(function (require) {
    var ImgCache = require("imgcache");
});

To use this library with CommonJS:

var cache = require("imgcache");

Setup your cache

Before initializing the cache, you must specify any default option you wish to override:

// write log to console
ImgCache.options.debug = true;

// increase allocated space on Chrome to 50MB, default was 10MB
ImgCache.options.chromeQuota = 50*1024*1024;

See ImgCache.options at the top of the source file for more settings.

After setting any custom configuration, initialize the cache:

ImgCache.init(function () {
    alert('ImgCache init: success!');

    // from within this function you're now able to call other ImgCache methods
    // or you can wait for the ImgCacheReady event

}, function () {
    alert('ImgCache init: error! Check the log for errors');
});

If the cache successfully initializes, ImgCache.ready will be set to true. You can also watch for the triggered ImgCacheReady event.

For PhoneGap/Cordova, ImgCache.init() must be called after the onDeviceReady event has been triggered

Storing images

Images are stored into the local folder specified by ImgCache.options.localCacheFolder. To add a file to the cache:

ImgCache.cacheFile('http://my-cdn.com/users/2/profile.jpg');

To cache an image defined as a background image, you can either use cacheFile or use the helper function ImgCache.cacheBackground that accepts a DOM/jQuery element, retrieves its background attribute and cache that file.

Using cached images

Once an image is stored in the cache, you can replace the file displayed in an img element by the cached one:

var target = $('img#profile');
ImgCache.cacheFile(target.attr('src'), function () {
  ImgCache.useCachedFile(target, function () {
    alert('now using local copy');
  }, function(){
    alert('could not load from cache');
  })
});

To check if a file is stored locally:

ImgCache.isCached(target.attr('src'), function(path, success) {
  if (success) {
    // already cached
    ImgCache.useCachedFile(target);
  } else {
    // not there, need to cache the image
    ImgCache.cacheFile(target.attr('src'), function () {
      ImgCache.useCachedFile(target);
    });
  }
});

When you no longer want to use the locally cached file:

var target = $('img#profile');
ImgCache.useOnlineFile(target);

Clearing the cache

ImgCache.clearCache(function () {
  // continue cleanup...
}, function () {
  // something went wrong
});

Important Methods

ImgCache.init() -- initialises the local cache

ImgCache.cacheFile() -- writes a copy of a file into the local cache

ImgCache.isCached() -- checks if a the given image exists in the cache - does not check if the latest version of that file is cached

ImgCache.getCachedFile() -- returns the cached file

ImgCache.getCachedFileURL() -- returns the URL of the cached version of a file

ImgCache.useCachedFile() -- replaces the img src with the cached version

ImgCache.useCachedFileWithSource() -- similar to useCachedFile but with the image source url as extra parameter

ImgCache.useOnlineFile() -- replaces back the img src with the original (online) version // synchronous method

ImgCache.clearCache() -- clears the local cache folder

ImgCache.isBackgroundCached() -- checks if a the given element background image exists in the cache - does not check if the latest version of that file is cached

ImgCache.cacheBackground() -- caches the background image of an element

ImgCache.useCachedBackground() -- replaces the background image source of the given element with the cached version

ImgCache.useBackgroundOnlineFile() -- replaces back a background image with the original (online) version

ImgCache.removeFile() -- removes a given file from the cache