thoughts/node_modules/ngstorage/README.md
node_modules/ngstorage/README.mdRaw
1ngStorage
2=========
3
4[](https://travis-ci.org/gsklee/ngStorage)
5[](https://david-dm.org/gsklee/ngStorage)
6[](https://david-dm.org/gsklee/ngStorage#info=devDependencies)
7
8An [AngularJS](https://github.com/angular/angular.js) module that makes Web Storage working in the *Angular Way*. Contains two services: `$localStorage` and `$sessionStorage`.
9
10### Differences with Other Implementations
11
12* **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.
13
14* **sessionStorage** - We got this often-overlooked buddy covered.
15
16* **Cleanly-Authored Code** - Written in the *Angular Way*, well-structured with testability in mind.
17
18* **No Cookie Fallback** - With Web Storage being [readily available](http://caniuse.com/namevalue-storage) in [all the browsers AngularJS officially supports](http://docs.angularjs.org/misc/faq#canidownloadthesourcebuildandhosttheangularjsenvironmentlocally), such fallback is largely redundant.
19
20Install
21=======
22
23### Bower
24
25```bash
26bower install ngstorage
27```
28
29*NOTE:* We are `ngstorage` and *NOT* `ngStorage`. The casing is important!
30
31### NPM
32```bash
33npm install ngstorage
34```
35
36*NOTE:* We are `ngstorage` and *NOT* `ngStorage`. The casing is important!
37
38### nuget
39
40```bash
41Install-Package gsklee.ngStorage
42```
43
44Or search for `Angular ngStorage` in the nuget package manager. <https://www.nuget.org/packages/gsklee.ngStorage>
45
46CDN
47===
48
49### cdnjs
50cdnjs now hosts ngStorage at <https://cdnjs.com/libraries/ngStorage>
51
52To use it
53
54``` html
55<script src="https://cdnjs.cloudflare.com/ajax/libs/ngStorage/0.3.6/ngStorage.min.js"></script>
56```
57
58### jsDelivr
59
60jsDelivr hosts ngStorage at <http://www.jsdelivr.com/#!ngstorage>
61
62To use is
63
64``` html
65<script src="https://cdn.jsdelivr.net/ngstorage/0.3.6/ngStorage.min.js"></script>
66```
67
68Usage
69=====
70
71### Require ngStorage and Inject the Services
72
73```javascript
74angular.module('app', [
75 'ngStorage'
76]).controller('Ctrl', function(
77 $scope,
78 $localStorage,
79 $sessionStorage
80){});
81```
82
83### Read and Write | [Demo](http://plnkr.co/edit/3vfRkvG7R9DgQxtWbGHz?p=preview)
84
85Pass `$localStorage` (or `$sessionStorage`) by reference to a hook under `$scope` in plain ol' JavaScript:
86
87```javascript
88$scope.$storage = $localStorage;
89```
90
91And use it like you-already-know:
92
93```html
94<body ng-controller="Ctrl">
95 <button ng-click="$storage.counter = $storage.counter + 1">{{$storage.counter}}</button>
96</body>
97```
98
99> Optionally, specify default values using the `$default()` method:
100>
101> ```javascript
102> $scope.$storage = $localStorage.$default({
103> counter: 42
104> });
105> ```
106
107With this setup, changes will be automatically sync'd between `$scope.$storage`, `$localStorage`, and localStorage - even across different browser tabs!
108
109### Read and Write Alternative (Not Recommended) | [Demo](http://plnkr.co/edit/9ZmkzRkYzS3iZkG8J5IK?p=preview)
110
111If you're not fond of the presence of `$scope.$storage`, you can always use watchers:
112
113```javascript
114$scope.counter = $localStorage.counter || 42;
115
116$scope.$watch('counter', function() {
117 $localStorage.counter = $scope.counter;
118});
119
120$scope.$watch(function() {
121 return angular.toJson($localStorage);
122}, function() {
123 $scope.counter = $localStorage.counter;
124});
125```
126
127This, 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.
128
129### Delete | [Demo](http://plnkr.co/edit/o4w3VGqmp8opfrWzvsJy?p=preview)
130
131Plain ol' JavaScript again, what else could you better expect?
132
133```javascript
134// Both will do
135delete $scope.$storage.counter;
136delete $localStorage.counter;
137```
138
139This will delete the corresponding entry inside the Web Storage.
140
141### Delete Everything | [Demo](http://plnkr.co/edit/YiG28KTFdkeFXskolZqs?p=preview)
142
143If you wish to clear the Storage in one go, use the `$reset()` method:
144
145```javascript
146$localStorage.$reset();
147````
148
149> Optionally, pass in an object you'd like the Storage to reset to:
150>
151> ```javascript
152> $localStorage.$reset({
153> counter: 42
154> });
155> ```
156
157### Permitted Values | [Demo](http://plnkr.co/edit/n0acYLdhk3AeZmPOGY9Z?p=preview)
158
159You can store anything except those [not supported by JSON](http://www.json.org/js.html):
160
161* `Infinity`, `NaN` - Will be replaced with `null`.
162* `undefined`, Function - Will be removed.
163
164### Usage from config phase
165
166To read and set values during the Angular config phase use the `.get/.set`
167functions provided by the provider.
168
169```javascript
170var app = angular.module('app', ['ngStorage'])
171.config(['$localStorageProvider',
172 function ($localStorageProvider) {
173 $localStorageProvider.get('MyKey');
174
175 $localStorageProvider.set('MyKey', { k: 'value' });
176 }]);
177```
178
179### Prefix
180
181To change the prefix used by ngStorage use the provider function `setKeyPrefix`
182during the config phase.
183
184```javascript
185var app = angular.module('app', ['ngStorage'])
186.config(['$localStorageProvider',
187 function ($localStorageProvider) {
188 $localStorageProvider.setKeyPrefix('NewPrefix');
189 }])
190```
191
192### Custom serialization
193
194To change how ngStorage serializes and deserializes values (uses JSON by default) you can use your own functions.
195
196```javascript
197angular.module('app', ['ngStorage'])
198.config(['$localStorageProvider',
199 function ($localStorageProvider) {
200 var mySerializer = function (value) {
201 // Do what you want with the value.
202 return value;
203 };
204
205 var myDeserializer = function (value) {
206 return value;
207 };
208
209 $localStorageProvider.setSerializer(mySerializer);
210 $localStorageProvider.setDeserializer(myDeserializer);
211 }];)
212```
213
214### Minification
215Just run `$ npm install` to install dependencies. Then run `$ grunt` for minification.
216
217### Hints
218
219#### Watch the watch
220
221ngStorage 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.
222Normally this is not a problem, but, for example, if you launch a new window after saving a value...
223
224```javascript
225$scope.$storage.school = theSchool;
226$log.debug("launching " + url);
227var myWindow = $window.open("", "_self");
228myWindow.document.write(response.data);
229```
230
231the 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:
232
233```javascript
234$scope.$storage.school = theSchool;
235$log.debug("launching and saving the new value" + url);
236$timeout(function(){
237 var myWindow = $window.open("", "_self");
238 myWindow.document.write(response.data);
239});
240```
241
242or better using `$scope.$evalAsync` as:
243
244```javascript
245$scope.$storage.school = theSchool;
246$log.debug("launching and saving the new value" + url);
247$scope.$evalAsync(function(){
248 var myWindow = $window.open("", "_self");
249 myWindow.document.write(response.data);
250});
251```
252
253And your new values will be persisted correctly.
254
255Todos
256=====
257
258* ngdoc Documentation
259* Namespace Support
260* Unit Tests
261* Grunt Tasks
262
263Any contribution will be appreciated.