An Angular module that gives you access to the browsers local storage, v0.1.5
##Table of contents:
- Get Started
- Development
- Configuration
- setPrefix
- setStorageType
- setStorageCookie
- setStorageCookieDomain
- setNotify
- Example
- API Documentation
- isSupported
- getStorageType
- set
- get
- keys
- remove
- clearAll
- bind
- deriveKey
- length
- cookie
##Get Started
(1) You can install angular-local-storage using 2 different ways:
Git:
clone & build this repository
Bower:
$ bower install angular-local-storagenpm:
$ 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:
<!doctype html>
<html ng-app="myApp">
<head>
</head>
<body>
...
<script src="//ajax.googleapis.com/ajax/libs/angularjs/1.1.5/angular.min.js"></script>
<script src="bower_components/js/angular-local-storage.min.js"></script>
...
<script>
var myApp = angular.module('myApp', ['LocalStorageModule']);
</script>
...
</body>
</html>##Configuration
###setPrefix
You could set a prefix to avoid overwriting any local storage variables from the rest of your app
Default prefix: ls.<your-key>
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setPrefix('yourAppName');
});###setStorageType
You could change web storage type to localStorage or sessionStorage
Default storage: localStorage
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: '/'
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setStorageCookie(45, '<path>');
});###setStorageCookieDomain
Set the cookie domain, since this runs inside a the config() block, only providers and constants can be injected. As a result, $location service can't be used here, use a hardcoded string or window.location.
No default value
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setStorageCookieDomain('<domain>');
});###setNotify
Send signals for each of the following actions:
setItem , default: true
removeItem , default: false
myApp.config(function (localStorageServiceProvider) {
localStorageServiceProvider
.setNotify(true, true);
});###Configuration Example Using all together
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
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
if(localStorageService.isSupported) {
//...
}
//...
});###getStorageType
Returns: String
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
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
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
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
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
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.
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
localStorageService.set('property', 'oldValue');
$scope.unbind = localStorageService.bind($scope, 'property');
//Test Changes
$scope.update = function(val) {
$scope.property = val;
$timeout(function() {
alert("localStorage value: " + localStorageService.get('property'));
});
}
//...
});<div ng-controller="MainCtrl">
<p>{{property}}</p>
<input type="text" ng-model="lsValue"/>
<button ng-click="update(lsValue)">update</button>
<button ng-click="unbind()">unbind</button>
</div>###deriveKey
Return the derive key
Returns String
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
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
var lsLength = localStorageService.length(); // e.g: 7
//...
});##Cookie
Deal with browser's cookies directly.
##cookie.isSupported
Checks if cookies are enabled in the browser.
Returns: Boolean
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
if(localStorageService.cookie.isSupported) {
//...
}
//...
});###cookie.set
Directly adds a value to cookies.
Note: Typically used as a fallback if local storage is not supported.
Returns: Boolean
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
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function getItem(key) {
return localStorageService.cookie.get(key);
}
//...
});###cookie.remove
Remove directly value from a cookie.
Returns: Boolean
myApp.controller('MainCtrl', function($scope, localStorageService) {
//...
function removeItem(key) {
return localStorageService.cookie.remove(key);
}
//...
});###clearAll
Remove all data for this app from cookie.
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:
- Don't forget about tests.
- If you planning add some feature please create issue before.
Clone the project:
$ git clone https://github.com/<your-repo>/angular-local-storage.git
$ npm install
$ bower installRun the tests:
$ grunt testDeploy:
Run the build task, update version before(bower,package)
$ grunt dist
$ git tag 0.*.*
$ git push origin master --tags