angular-local-storage
=====================
An Angular module that gives you access to the browsers local storage, **v0.1.2**
[](https://travis-ci.org/grevory/)
##Table of contents:
- [Get Started](#get-started)
- [Configuration](#configuration)
- [setPrefix](#setprefix)
- [setStorageType](#setstoragetype)
- [setStorageCookie](#setstoragecookie)
- [setStorageCookieDomain](#setstoragecookiedomain)
- [setNotify](#setnotify)
- [Example](#configuration-example)
- [API Documentation](#api-documentation)
- [isSupported](#issupported)
- [getStorageType](#getstoragetype)
- [set](#set)
- [get](#get)
- [keys](#keys)
- [remove](#remove)
- [clearAll](#clearall)
- [bind](#bind)
- [deriveKey](#derivekey)
- [length](#length)
- [cookie](#cookie)
- [set](#cookieset)
- [get](#cookieget)
- [remove](#cookieremove)
- [clearAll](#cookieclearall)
##Get Started
**(1)** You can install angular-local-storage using 2 different ways:
**Git:**
clone & build [this](https://github.com/grevory/angular-local-storage.git) repository
**Bower:**
```bash
$ bower install angular-local-storage
```
**npm:**
```bash
$ npm install angular-local-storage
```
**(2)** Include `angular-local-storage.js` (or `angular-local-storage.min.js`) in your `index.html`, after including Angular itself.
**(3)** Add `'LocalStorageModule'` to your main module's list of dependencies.
When you're done, your setup should look similar to the following:
```html
...
...
...
```
##Configuration
###setPrefix
You could set a prefix to avoid overwriting any local storage variables from the rest of your app
**Default prefix:** `ls.`
```js
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setPrefix('yourAppName');
});
```
###setStorageType
You could change web storage type to localStorage or sessionStorage
**Default storage:** `localStorage`
```js
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setStorageType('sessionStorage');
});
```
###setStorageCookie
Set cookie options (usually in case of fallback)
**expiry:** number of days before cookies expire (0 = does not expire). **default:** `30`
**path:** the web path the cookie represents. **default:** `'/'`
```js
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setStorageCookie(45, '');
});
```
###setStorageCookieDomain
Set for cookie domain
**No default value**
```js
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setStorageCookieDomain('');
});
```
###setNotify
Send signals for each of the following actions:
**setItem** , default: `true`
**removeItem** , default: `false`
```js
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setNotify(true, true);
});
```
###Configuration Example
Using all together
```js
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setPrefix('myApp')
.setStorageType('sessionStorage')
.setNotify(true, true)
});
```
##API Documentation
##isSupported
Checks if the browser support the current storage type(e.g: `localStorage`, `sessionStorage`).
**Returns:** `Boolean`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
if(localStorageService.isSupported) {
//...
}
//...
});
```
###getStorageType
**Returns:** `String`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
var storageType = localStorageService.getStorageType(); //e.g localStorage
//...
});
```
###set
Directly adds a value to local storage.
If local storage is not supported, use cookies instead.
**Returns:** `Boolean`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function submit(key, val) {
return localStorageService.set(key, value);
}
//...
});
```
###get
Directly get a value from local storage.
If local storage is not supported, use cookies instead.
**Returns:** `value from local storage`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function getItem(key) {
return localStorageService.get(key);
}
//...
});
```
###keys
Return array of keys for local storage, ignore keys that not owned.
**Returns:** `value from local storage`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
var lsKeys = localStorageService.keys();
//...
});
```
###remove
Remove an item from local storage by key.
If local storage is not supported, use cookies instead.
**Returns:** `Boolean`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function removeItem(key) {
return localStorageService.remove(key);
}
//...
});
```
###clearAll
Remove all data for this app from local storage.
If local storage is not supported, use cookies instead.
**Note:** Optionally takes a regular expression string and removes matching.
**Returns:** `Boolean`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function clearNumbers(key) {
return localStorageService.clearAll(/^\d+$/);
}
//...
function clearAll() {
return localStorageService.clearAll();
}
});
```
###bind
Bind $scope key to localStorageService.
**Usage:** `localStorageService.bind(scope, property, value[optional], key[optional])`
***key:*** The corresponding key used in local storage
**Returns:** deregistration function for this listener.
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
localStorageService.set('property', 'oldValue');
var unbind = localStorageService.bind($scope, 'property');
//Test Changes
$scope.property = 'newValue1';
console.log(localStorageService.get('property')) // newValue1;
//unbind watcher
unbind();
$scope.property = 'newValue2';
console.log(localStorageService.get('property')) // newValue1;
//...
});
```
###deriveKey
Return the derive key
**Returns** `String`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
localStorageService.set('property', 'oldValue');
//Test Result
console.log(localStorageService.deriveKey('property')); // ls.property
//...
});
```
###length
Return localStorageService.length, ignore keys that not owned.
**Returns** `Number`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
var lsLength = localStorageService.length(); // e.g: 7
//...
});
```
##Cookie
Deal with browser's cookies directly.
###cookie.set
Directly adds a value to cookies.
**Note:** Typically used as a fallback if local storage is not supported.
**Returns:** `Boolean`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function submit(key, val) {
return localStorageService.cookie.set(key, value);
}
//...
});
```
###cookie.get
Directly get a value from a cookie.
**Returns:** `value from local storage`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function getItem(key) {
return localStorageService.cookie.get(key);
}
//...
});
```
###cookie.remove
Remove directly value from a cookie.
**Returns:** `Boolean`
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function removeItem(key) {
return localStorageService.cookie.remove(key);
}
//...
});
```
###clearAll
Remove all data for this app from cookie.
```js
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function clearAll() {
return localStorageService.cookie.clearAll();
}
});
```
Check out the full demo at http://gregpike.net/demos/angular-local-storage/demo.html
##Development:
Clone the project:
```bash
$ git clone https://github.com//angular-local-storage.git
$ npm install
$ bower install
```
Run the tests:
```bash
$ grunt test
```
**Deploy:**
Run the build task, update version before(bower,package)
```bash
$ grunt dist
$ git tag 0.*.*
$ git push origin master --tags
```