cordova-file-cache
Super Awesome File Cache for Cordova Apps
Based on cordova-promise-fs.
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 Cachevar cache = fs: // 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; cacheready
- 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
atlocalRoot
. - 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 filescachecache // automatically prepends the `severRoot`cache // Now the cache is dirty: It needs to download.cache === true// cache.add also returns if the cache is dirty.var dirty = cache // 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 { var progress ="Progress: " + equeueIndex // current download index + " " + equeueSize; // total files to download // Download files.cache }
Use the cache
// Get the cached internalURL of the file: "cdvfile://localhost/persisent/cache/photo3.jpg"cache; cache;cache; // Get the file URL of the file: "file://.../photo3.jpg";cache; // When file is not cached, the server URL is returned as a fallback.cache === 'http://yoursever.com/never-cached-this.jpg'cache === 'http://yoursever.com/never-cached-this.jpg' // Get Base64 encoded data URL.cache;
Other functions
// Abort all downloadscache // Clear cache (removes localRoot directory)cacheclear // Or remove a single filecache // Returns path on Cordova Filesystem, i.e. "/cache/photo3.jpg"cache; // Returns server URL to download, i.e. "http://yourserver.com/photo3.jpg";cache; // Needs a download?cache; // Returns a list of server URLs that need to be downloaded.cache; // Return a list of paths that are cached (i.e. ["/cache/photo3.jpg"])cache
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 -gnpm 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
© 2014 - Mark Marijnissen