angular-localforage-setitems1.0.0 • Public • Published
Angular service & directive for https://github.com/mozilla/localForage (Offline storage, improved.)
Store your data in the best available storage solution that your browser can offer (IndexedDB / WebSQL or localstorage as a fallback)
Everything is async and uses promises
Use the service or the directive
- Download the project or install via bower
bower install angular-localforageor npm
npm install angular-localforage
- Download localForage https://github.com/mozilla/localForage
- Put localforage.js and angular-localForage.js into your project (with localforage.js before angular-localForage.js).
- Add the module
LocalForageModuleto your application
- (optional) Configure the
$localForageProvider. See below for details.
- Use the
$localForageservice or the
setDriver(driver): you can force the driver to use, check the localForage documentation for more information
driver(): returns the current localForage driver (sync)
setItem(key/Array<key>, value/Array<value>): stores data (async, promise)
getItem(key/Array<key>, rejectIfNull): retrieves stored data, rejects if rejectIfNull is truthy and one of the values is null (async, promise)
localForage will return null for a lookup on a key that does not exist. If you set
true, it will reject the promise if the value (or one of the values of the array lookup) is null. If
you normally store
null in the database, you can use the single arity version of the function to
retrieve the null value, but you have no way to know if you've retrieved
null or if the key did
removeItem(key/Array<key>): removes stored data (async, promise)
pull(key/Array<key>): removes stored data and returns it (it's like doing getItem followed by removeItem) (async, promise)
clear(): removed all stored data for your application based on the app prefix (async, promise)
key(n): retrieves the key at n position in storage. It doesn't take the prefix into account if you use localStorage (async, promise)
keys(): returns all the keys used for storage in your application (async, promise)
length(): returns the number of items stored (async, promise)
iterate(iteratorCallback): Iterate over all value/key pairs in datastore. (async, promise)
Iterate supports early exit by returning non
undefined value inside
Resulting value will be passed to the promise as the result of iteration.
You can use this to make a search in your data:
bind($scope, key/params object): lets you directly bind a LocalForage value to a $scope variable (async, promise)
Note: It only binds when the object is already stored in the database or when you provide a default value.
unbind($scope, key[, scopeKey]): lets you unbind a variable from localForage while removing the value from both the scope and the storage (async, promise)
You can directly bind a scope value from within your html. With the
local-forage directive, you can either use just the key parameter:
Or give an object parameter:
key is the only required parameter. The other options are:
name: if you want to store your values in a specific instance (See below for more info on multiple instances)
scopeKey: if you want to store the value in the scope under a different key from the one in storage. You can for example use a specific key of an object by using
defaultValue: if you want to define a ...default value
Configure the provider :
You can configure the
$localForageProvider. Any parameter that you set here will be the default for any new localforage instance.
You can for example set your own prefix for storage (by default
lf is used).
You can also choose to be notified by broadcast on set and remove.
The broadcast are the following :
You can use multiple instances of localForage at the same time. To create a new instance, call
createInstance with a config object (sync):
var lf2 = $localForage;
The parameters will inherit the default parameters that you might have configured in the config phase of your application (See above for details), but the new config object will overwrite them.
It means that you can have one instance using localStorage, and one instance using indexedDB/WebSQL, at the same time !
The instance will take the name that you will define in the config object. You can get an instance previously created by using the
var lf2 = $localForage;
instance method will return the default instance if you don't give a name parameter.
Download the required libs :
npm install bower install
Then start the tests with :
It will launch Chrome and Firefox, edit the
karma task in
gulpfile.js if you want to change
something. We could use more tests, see "contributing" below.
I would love to have community contributions and support! A few areas where could use help right now:
- Writing tests
- Elaborating on documentation
- Creating examples for the docs
- Bug reports and/or fixes
If you want to contribute, please submit a pull request, or contact email@example.com for more information.
The commits messages need to be validated. Use the following commands to add a git hook that will check if you follow the convention :
ln -s ../../validate-commit-msg.js .git/hooks/commit-msg
When you commit your messages, follow this convention :
<type>: <subject> <BLANK LINE> <optional message>
feat: Added validation commit msg fileInstallation:* cd <angular-localForage-repo>* ln -s ../../validate-commit-msg.js .git/hooks/commit-msg
The following types are accepted in the commit messages:
But only feat/fix/docs/perf will be in the changelog.
If you do a breaking change, add an explanation preceded by
BREAKING CHANGE:. For example:
fix: remove deprecated promise unwrappingBREAKING CHANGE: promise unwrapping has been removed.It can no longer be turned on.
If you want to reference an issue, you can add a new line with either
Fixes followed by the issue number. For example:
feat: Added changelog auto generationUsage: gulp changelogFixes #62
You can fix / close multiple issue with one commit, just add a new line for each.