cordova-file-cache

Super Awesome File Cache for Cordova Apps

Getting started

  # fetch code using bower
  bower install cordova-file-cache cordova-promise-fs
  # ...or npm...
  npm install cordova-file-cache cordova-promise-fs

  # install Cordova and plugins
  cordova platform add ios
  cordova plugin add cordova-plugin-file
  cordova plugin add cordova-plugin-file-transfer # optional

IMPORTANT: For iOS, use Cordova 3.7.0 or higher (due to a bug that affects requestFileSystem).

Or just download and include CordovaPromiseFS.js and CordovaFileCache.js

Usage

Initialize & configuration

// Initialize a Cache
var cache = new CordovaFileCache({
  fs: new CordovaPromiseFS({ // An instance of CordovaPromiseFS is REQUIRED
      Promise: Promise // <-- your favorite Promise lib (REQUIRED)
  }),
  mode: 'hash', // or 'mirror', optional
  localRoot: 'data', //optional
  serverRoot: 'http://yourserver.com/files/', // optional, required on 'mirror' mode
  cacheBuster: false  // optional
});

cache.ready.then(function(list){
    // Promise when cache is ready.
    // Returns a list of paths on the FileSystem that are cached.
})

CordovaPromiseFS is REQUIRED!
You need to include a Promise library when creating a CordovaPromiseFS. Any library that follows the A+ spec will work. For example: bluebird or promiscuous.
mode: "mirror": Mirrors the file structure from serverRoot at localRoot.
mode: "hash": Filename is hash of server url (plus extension).
CordovaPromiseFS() is an instance of cordova-promise-fs.
cacheBuster appends a timestamp to the url ?xxxxxx to avoid the network cache.

Add files to the cache


// First, add files
cache.add('http://yourserver.com/folder/photo1.jpg')
cache.add('folder/photo2.jpg')  // automatically prepends the `severRoot`
cache.add(['photo3.jpg','photo4.jpg'])

// Now the cache is dirty: It needs to download.
cache.isDirty() === true
// cache.add also returns if the cache is dirty.
var dirty = cache.add(['photo3.jpg'])

// Downloading files.
// The optional 'onprogress' event handler is enhanced with information
// about the total download queue.
// It is recommended to avoid heavy UI and animation while downloading.
//
// The optional 'includeFileProgress' defaults to "false".
// When set to "true", you will also receive progress events from individual file tranfers.
//
// "false" is recommended as sending many FileTransfer progress events from native to JS can
// slow down performance.
var onprogress = function(e) {
  var progress ="Progress: "
  + e.queueIndex // current download index
  + " "
  + e.queueSize; // total files to download

// Download files.
cache.download(onprogress,includeFileProgress).then(function(cache){ ... },function(failedDownloads) { ... })

}

Use the cache

// Get the cached internalURL of the file: "cdvfile://localhost/persisent/cache/photo3.jpg"
cache.get('photo3.jpg');           
cache.toInternalURL('photo3.jpg');
cache.toInternalURL('http://yourserver.com/photo3.jpg');

// Get the file URL of the file: "file://.../photo3.jpg";
cache.toURL('photo3.jpg');

// When file is not cached, the server URL is returned as a fallback.
cache.get('http://yoursever.com/never-cached-this.jpg') === 'http://yoursever.com/never-cached-this.jpg'
cache.get('never-cached-this.jpg') === 'http://yoursever.com/never-cached-this.jpg'

// Get Base64 encoded data URL.
cache.toDataURL('photo3.jpg').then(function(base64){},function(err){});

Other functions

// Abort all downloads
cache.abort()

// Clear cache (removes localRoot directory)
cache.clear().then( ... )

// Or remove a single file
cache.remove('photo3.jpg').then( ... )

// Returns path on Cordova Filesystem, i.e. "/cache/photo3.jpg"
cache.toPath('photo3.jpg');      

// Returns server URL to download, i.e. "http://yourserver.com/photo3.jpg";
cache.toServerURL('photo3.jpg');

// Needs a download?
cache.isDirty();

// Returns a list of server URLs that need to be downloaded.
cache.getDownloadQueue();        

 // Return a list of paths that are cached (i.e. ["/cache/photo3.jpg"])
cache.list().then(function(list){...},function(err){...})

Changelog

1.2.2 - bugfixes

When download is ready, fail if there are no errors instead of fail if cache is dirty (again)

1.2.0

Return errors when not all files are loaded instead of empty array

1.1.0

Update cordova-promise-fs to 1.1.0
Default download progress events only updates on download finished (performance boost!)

1.0.0

Update to cordova-promise-fs 1.0.0

0.14.0 (07/02/2016)

Handle REST api calls better (thanks @xontab)
Fix download onprogress index

0.13.0 (23/01/2016)

Fix download onprogress index

0.12.0 (18/03/2015)

Export hash function as CordovaFileCache.hash (needed by App Loader)

0.11.0 (17/03/2015)

Update CordovaPromiseFS dependency.
Fix some errors in README

0.10.0 (21/12/2014)

Update CordovaPromiseFS dependency

0.9.0 (21/12/2014)

Bugfix with cacheBuster

0.8.0 (28/11/2014)

Normalized path everywhere.

0.7.0 (27/11/2014)

Added tests and fixed few minor bugs

0.6.0 (19/11/2014)

Bugfix: changes to "get" and "toInternalURL" methods.
Bugfix: LocalRoot should NOT start with a slash (Android)

0.5.0 (15/11/2014)

Bugfix: Make sure cache returns a valid server URL if file is not cached.

0.4.0 (13/11/2014)

Added Chrome Support!

0.3.0 (09/11/2014)

Added cacheBuster option.

0.2.0 (07/11/2014)

Many small bugfixes
Upgraded the build process with webpack

0.1.0 (06/11/2014)

Contribute

Convert CommonJS to a browser-version:

npm install webpack -g
npm run-script prepublish

Feel free to contribute to this project in any way. The easiest way to support this project is by giving it a star.

Contact

@markmarijnissen
http://www.madebymark.nl
info@madebymark.nl

markmarijnissen / cordova-file-cache

readme