The purpose of this JS library is to provide a nice interface for locally storing images for offline apps using PhoneGap/Cordova or browsers supporting the new html5 File API (e.g. Chrome).
This library is especially useful for mobile web applications using Phonegap/Cordova where the normal browser cache cannot be relied upon and where offline navigation is quite common.
Used with imagesloaded as shown in examples/example2.html, you can see that it can automatically:
This is the best solution I have found so far to provide easy caching of images within a phonegap web app.
This library works with Phonegap/Cordova (v >= 1.7), the supported platforms being:
Most methods are ASYNCHRONOUS : use callbacks if required.
This library uses plain old ES5 JavaScript with no transpiler and has no dependency.
Note: You can use bower or npm to add this library as a dependency to your project (repository name: imgcache.js).
To start to use this library, import lib/imgcache.js within your html file:
<script src="https://github.com/chrisben/imgcache.js/raw/master/lib/imgcache.js"></script>Using with PhoneGap/Cordova: see CORDOVA.md.
Using with Chrome or other browsers that support the [html5 filesystem API]:
--allow-file-access-from-files --allow-file-access otherwise the local filesystem will not be accessible (security error)define(function (require) {
var ImgCache = require("imgcache");
});var cache = require("imgcache");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;
// Instead of using the PERSISTENT or TEMPORARY filesystems, use one of the
// Cordova File plugin's app directories
// (https://github.com/apache/cordova-plugin-file#where-to-store-files).
// This is friendlier in a mobile application environment as we are able to store
// files in the correct platform-recommended/enforced directories.
// WARNING: Make sure this points to a __directory__!
// NOTE: Only has effect when running in a Cordova environment
ImgCache.options.cordovaFilesystemRoot = cordova.file.dataDirectory;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.
If you're using imgcache.js with PhoneGap/Cordova, ImgCache.init() must be called after the onDeviceReady event has been triggered, not before!
Note that in Chrome, the user will be prompted to give permission to the page for accessing the local filesystem (which will run the error callback if they refuse).
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.
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);To remove all cached files, clear the local cache folder:
ImgCache.clearCache(function () {
// continue cleanup...
}, function () {
// something went wrong
});There is currently no way to invalidate single images from the cache.
Private methods are accessible through:
See ImgCache.options at the top of the source file for the list of options. Options can be overridden from your own script, no need to modify the library!
Include the imgcache-promise.js wrapper into your project to be able to use ES6-compatible Promises (using Bluebird for instance) if you don't like callbacks and prefer to use the simpler then/catch methods.
This wrapper also makes sure the init method is always called first, so you SHOULDN'T call this method yourself when using this wrapper.
Check out the sample code.
Run a local server:
npm install
npm startThen open the given url in your Chrome browser (index.html) and click 'Start unit tests' to launch unit tests.
You will be able to find several code samples.
To lint the main javascript code, you can run npm test to start eslint
See CHANGELOG for the complete release notes.
Make sure you first read carefully this documentation. If you are still having issues follow this checklist:
ImgCache.options.debug = true;) and follow the output within the console carefully.If using Cordova/Phonegap, make sure you read this documentation first, then double check the following:
If you are still stuck, look for a similar problem within existing issues.
If you cannot find any, open an issue with a description of your problem, a simpler version of your code if you can.
Whenever you post an issue it's IMPORTANT you add the following details to get a quicker answer:
See KNOWN_ISSUES for a list of known issues.
Wrappers for AngularJS:
Wrapper for Ionic Framework:
Ionic example:
Copyright 2012-2018 (c) Christophe BENOIT
Apache License - see LICENSE.md
Code from http://code.google.com/p/tiny-sha1/ is being used which is under the MIT License. The copyright for this part belongs to the creator of this work.