🌜
🌞
ngstorage

ngstorage

v0.3.11

ngStorage =========

npm install ngstorage

README

ngStorage

Build Status Dependency Status devDependency Status

An AngularJS module that makes Web Storage working in the Angular Way. Contains two services: $localStorage and $sessionStorage.

Differences with Other Implementations

  • No Getter 'n' Setter Bullshit - Right from AngularJS homepage: "Unlike other frameworks, there is no need to [...] wrap the model in accessors methods. Just plain old JavaScript here." Now you can enjoy the same benefit while achieving data persistence with Web Storage.

  • sessionStorage - We got this often-overlooked buddy covered.

  • Cleanly-Authored Code - Written in the Angular Way, well-structured with testability in mind.

  • No Cookie Fallback - With Web Storage being readily available in all the browsers AngularJS officially supports, such fallback is largely redundant.

Install

Bower

bower install ngstorage

NOTE: We are ngstorage and NOT ngStorage. The casing is important!

NPM

npm install ngstorage

NOTE: We are ngstorage and NOT ngStorage. The casing is important!

nuget

Install-Package gsklee.ngStorage

Or search for Angular ngStorage in the nuget package manager. https://www.nuget.org/packages/gsklee.ngStorage

CDN

cdnjs

cdnjs now hosts ngStorage at https://cdnjs.com/libraries/ngStorage

To use it

<script src="https://cdnjs.cloudflare.com/ajax/libs/ngStorage/0.3.6/ngStorage.min.js"></script>

jsDelivr

jsDelivr hosts ngStorage at http://www.jsdelivr.com/#!ngstorage

To use is

<script src="https://cdn.jsdelivr.net/ngstorage/0.3.6/ngStorage.min.js"></script>

Usage

Require ngStorage and Inject the Services

angular.module('app', [
    'ngStorage'
]).controller('Ctrl', function(
    $scope,
    $localStorage,
    $sessionStorage
){});

Read and Write | Demo

Pass $localStorage (or $sessionStorage) by reference to a hook under $scope in plain ol' JavaScript:

$scope.$storage = $localStorage;

And use it like you-already-know:

<body ng-controller="Ctrl">
    <button ng-click="$storage.counter = $storage.counter + 1">{{$storage.counter}}</button>
</body>

Optionally, specify default values using the $default() method:

$scope.$storage = $localStorage.$default({
    counter: 42
});

With this setup, changes will be automatically sync'd between $scope.$storage, $localStorage, and localStorage - even across different browser tabs!

If you're not fond of the presence of $scope.$storage, you can always use watchers:

$scope.counter = $localStorage.counter || 42;

$scope.$watch('counter', function() {
    $localStorage.counter = $scope.counter;
});

$scope.$watch(function() {
    return angular.toJson($localStorage);
}, function() {
    $scope.counter = $localStorage.counter;
});

This, however, is not the way ngStorage is designed to be used with. As can be easily seen by comparing the demos, this approach is way more verbose, and may have potential performance implications as the values being watched quickly grow.

Delete | Demo

Plain ol' JavaScript again, what else could you better expect?

// Both will do
delete $scope.$storage.counter;
delete $localStorage.counter;

This will delete the corresponding entry inside the Web Storage.

Delete Everything | Demo

If you wish to clear the Storage in one go, use the $reset() method:

$localStorage.$reset();

Optionally, pass in an object you'd like the Storage to reset to:

$localStorage.$reset({
    counter: 42
});

Permitted Values | Demo

You can store anything except those not supported by JSON:

  • Infinity, NaN - Will be replaced with null.
  • undefined, Function - Will be removed.

Usage from config phase

To read and set values during the Angular config phase use the .get/.set functions provided by the provider.

var app = angular.module('app', ['ngStorage'])
.config(['$localStorageProvider',
    function ($localStorageProvider) {
        $localStorageProvider.get('MyKey');

        $localStorageProvider.set('MyKey', { k: 'value' });
    }]);

Prefix

To change the prefix used by ngStorage use the provider function setKeyPrefix during the config phase.

var app = angular.module('app', ['ngStorage'])
.config(['$localStorageProvider',
    function ($localStorageProvider) {
        $localStorageProvider.setKeyPrefix('NewPrefix');
    }])

Custom serialization

To change how ngStorage serializes and deserializes values (uses JSON by default) you can use your own functions.

angular.module('app', ['ngStorage'])
.config(['$localStorageProvider', 
  function ($localStorageProvider) {
    var mySerializer = function (value) {
      // Do what you want with the value.
      return value;
    };
    
    var myDeserializer = function (value) {
      return value;
    };

    $localStorageProvider.setSerializer(mySerializer);
    $localStorageProvider.setDeserializer(myDeserializer);
  }];)

Minification

Just run $ npm install to install dependencies. Then run $ grunt for minification.

Hints

Watch the watch

ngStorage internally uses an Angular watch to monitor changes to the $storage/$localStorage objects. That means that a digest cycle is required to persist your new values into the browser local storage. Normally this is not a problem, but, for example, if you launch a new window after saving a value...

$scope.$storage.school = theSchool;
$log.debug("launching " + url);
var myWindow = $window.open("", "_self");
myWindow.document.write(response.data);

the new values will not reliably be saved into the browser local storage. Allow a digest cycle to occur by using a zero-value $timeout as:

$scope.$storage.school = theSchool;
$log.debug("launching and saving the new value" + url);
$timeout(function(){
   var myWindow = $window.open("", "_self");
   myWindow.document.write(response.data);
});

or better using $scope.$evalAsync as:

$scope.$storage.school = theSchool;
$log.debug("launching and saving the new value" + url);
$scope.$evalAsync(function(){
   var myWindow = $window.open("", "_self");
   myWindow.document.write(response.data);
});

And your new values will be persisted correctly.

Todos

  • ngdoc Documentation
  • Namespace Support
  • Unit Tests
  • Grunt Tasks

Any contribution will be appreciated.

Release Notes

0.3.9
By egilkh • Published on August 19, 2015

Sadly was some bugs. So have to do another release.

I apologize.

General

License
MIT
Typescript Types
Tree-shakeable
No

Popularity

GitHub Stargazers
2,342
Community Interest
2,932
Number of Forks
473

Maintenance

Commits
11/2110/2201
Last Commit
Sep 17, 2018
Open Issues
64
Closed Issues
107
Open Pull Requests
13
Closed Pull Requests
38

Versions

Versions Released
11/2110/2201
Latest Version Released
Aug 1, 2016
Current Tags
latest0.3.11
old-version0.3.7

Contributors

egilkh
egilkh
Commits: 80
kbaltrinic
kbaltrinic
Commits: 6
roaks3
roaks3
Commits: 5
lperrin
lperrin
Commits: 3
dcendents
dcendents
Commits: 3
stylenclass
stylenclass
Commits: 2
williamboman
williamboman
Commits: 2
krtek
krtek
Commits: 2
jak-pan
jak-pan
Commits: 1
jlkalberer
jlkalberer
Commits: 1
OverZealous
OverZealous
Commits: 1
everdimension
everdimension
Commits: 1
jcompagner
jcompagner
Commits: 1
alexgorbatchev
alexgorbatchev
Commits: 1
rortegax2
rortegax2
Commits: 1