Noodlings

A blog on ideas, technology, and self-mastery by Chris Chung

angular-local-storage

angular-local-storage

An Angular module that gives you access to the browsers local storage, v0.1.4

Build Status Coverage Status

##Table of contents:

##Get Started (1) You can install angular-local-storage using 2 different ways:
Git: clone & build this repository
Bower:

1

$ bower install angular-local-storage

npm:

1

$ npm install angular-local-storage

(2) Include 

1

angular-local-storage.js
(or 
1

angular-local-storage.min.js
) in your 
1

index.html
, after including Angular itself.

(3) Add 

1

'LocalStorageModule'
to your main module’s list of dependencies.

When you’re done, your setup should look similar to the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!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: 

1

ls.<your-key>


1
2
3
4

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setPrefix('yourAppName');
});

###setStorageType You could change web storage type to localStorage or sessionStorage
Default storage: 

1

localStorage


1
2
3
4

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: 

1

30

path: the web path the cookie represents. default: 
1

'/'


1
2
3
4

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setStorageCookie(45, '<path>');
});

###setStorageCookieDomain Set the cookie domain, since this runs inside a the 

1

config()
block, only providers and constants can be injected. As a result, 
1

$location
service can’t be used here, use a hardcoded string or 
1

window.location
.
No default value

1
2
3
4

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setStorageCookieDomain('<domain>');
});

###setNotify Send signals for each of the following actions:
setItem , default: 

1

true

removeItem , default: 
1

false


1
2
3
4

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setNotify(true, true);
});

###Configuration Example Using all together

1
2
3
4
5
6

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: 

1

localStorage
, 
1

sessionStorage
). Returns: 
1

Boolean


1
2
3
4
5
6
7

myApp.controller('MainCtrl', function($scope, localStorageService) {
  //...
  if(localStorageService.isSupported) {
    //...
  }
  //...
});

###getStorageType Returns: 

1

String


1
2
3
4
5

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: 

1

Boolean


1
2
3
4
5
6
7

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: 

1

value from local storage


1
2
3
4
5
6
7

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: 

1

value from local storage


1
2
3
4
5

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: 

1

Boolean


1
2
3
4
5
6
7

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: 

1

Boolean


1
2
3
4
5
6
7
8
9
10

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: 

1

localStorageService.bind(scope, property, value[optional], key[optional])

key: The corresponding key used in local storage Returns: deregistration function for this listener.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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'));
    });
  }
  //...
});

1
2
3
4
5
6

<div ng-controller="MainCtrl">
  <p></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 

1

String


1
2
3
4
5
6
7

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 

1

Number


1
2
3
4
5

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: 

1

Boolean


1
2
3
4
5
6
7

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: 

1

Boolean


1
2
3
4
5
6
7

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: 

1

value from local storage


1
2
3
4
5
6
7

myApp.controller('MainCtrl', function($scope, localStorageService) {
  //...
  function getItem(key) {
   return localStorageService.cookie.get(key);
  }
  //...
});

###cookie.remove Remove directly value from a cookie.
Returns: 

1

Boolean


1
2
3
4
5
6
7

myApp.controller('MainCtrl', function($scope, localStorageService) {
  //...
  function removeItem(key) {
   return localStorageService.cookie.remove(key);
  }
  //...
});

###clearAll Remove all data for this app from cookie.

1
2
3
4
5
6

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:

1
2
3

$ git clone https://github.com/<your-repo>/angular-local-storage.git
$ npm install
$ bower install

Run the tests:

1

$ grunt test

Deploy:
Run the build task, update version before(bower,package)

1
2
3

$ grunt dist
$ git tag 0.*.*
$ git push origin master --tags