1 | # ngx-webstorage
|
2 | ### Local and session storage - Angular service
|
3 | This library provides an easy to use service to manage the web storages (local and session) from your Angular application.
|
4 | It provides also two decorators to synchronize the component attributes and the web storages.
|
5 |
|
6 | ------------
|
7 |
|
8 | #### Index:
|
9 | * [Getting Started](#gstart)
|
10 | * [Services](#services):
|
11 | * [LocalStorageService](#s_localstorage)
|
12 | * [SessionStorageService](#s_sessionstorage)
|
13 | * [Decorators](#decorators):
|
14 | * [@LocalStorage](#d_localstorage)
|
15 | * [@SessionStorage](#d_sessionStorage)
|
16 | * [Known issues](#knownissues)
|
17 | * [Modify and build](#modifBuild)
|
18 |
|
19 | ------------
|
20 |
|
21 | ### Migrate from v2.x to the v3
|
22 |
|
23 | 1. Update your project to Angular 7+
|
24 | 2. Rename the module usages by <b>NgxWebstorageModule.forRoot()</b> *(before: Ng2Webstorage)*
|
25 | > The forRoot is now mandatory in the root module even if you don't need to configure the library
|
26 |
|
27 | ------------
|
28 |
|
29 | ### <a name="gstart">Getting Started</a>
|
30 |
|
31 | 1. Download the library using npm `npm install --save ngx-webstorage`
|
32 | 2. Declare the library in your main module
|
33 |
|
34 | ```typescript
|
35 | import {NgModule} from '@angular/core';
|
36 | import {BrowserModule} from '@angular/platform-browser';
|
37 | import {NgxWebstorageModule} from 'ngx-webstorage';
|
38 |
|
39 | @NgModule({
|
40 | declarations: [...],
|
41 | imports: [
|
42 | BrowserModule,
|
43 | NgxWebstorageModule.forRoot(),
|
44 | //NgxWebstorageModule.forRoot({ prefix: 'custom', separator: '.', caseSensitive:true })
|
45 | // The forRoot method allows to configure the prefix, the separator and the caseSensitive option used by the library
|
46 | // Default values:
|
47 | // prefix: "ngx-webstorage"
|
48 | // separator: "|"
|
49 | // caseSensitive: false
|
50 | ],
|
51 | bootstrap: [...]
|
52 | })
|
53 | export class AppModule {
|
54 | }
|
55 |
|
56 | ```
|
57 |
|
58 | 3. Inject the services you want in your components and/or use the available decorators
|
59 |
|
60 | ```typescript
|
61 | import {Component} from '@angular/core';
|
62 | import {LocalStorageService, SessionStorageService} from 'ngx-webstorage';
|
63 |
|
64 | @Component({
|
65 | selector: 'foo',
|
66 | template: `foobar`
|
67 | })
|
68 | export class FooComponent {
|
69 |
|
70 | constructor(private localSt:LocalStorageService) {}
|
71 |
|
72 | ngOnInit() {
|
73 | this.localSt.observe('key')
|
74 | .subscribe((value) => console.log('new value', value));
|
75 | }
|
76 |
|
77 | }
|
78 | ```
|
79 |
|
80 | ```typescript
|
81 | import {Component} from '@angular/core';
|
82 | import {LocalStorage, SessionStorage} from 'ngx-webstorage';
|
83 |
|
84 | @Component({
|
85 | selector: 'foo',
|
86 | template: `{{boundValue}}`,
|
87 | })
|
88 | export class FooComponent {
|
89 |
|
90 | @LocalStorage()
|
91 | public boundValue;
|
92 |
|
93 | }
|
94 | ```
|
95 |
|
96 | ### <a name="services">Services</a>
|
97 | --------------------
|
98 |
|
99 | ### <a name="s_localstorage">`LocalStorageService`</a>
|
100 |
|
101 | #### Store( key:`string`, value:`any` ):`void`
|
102 | > create or update an item in the local storage
|
103 |
|
104 | ##### Params:
|
105 | - **key**: String. localStorage key.
|
106 | - **value**: Serializable. value to store.
|
107 |
|
108 | ##### Usage:
|
109 | ````typescript
|
110 | import {Component} from '@angular/core';
|
111 | import {LocalStorageService} from 'ngx-webstorage';
|
112 |
|
113 | @Component({
|
114 | selector: 'foo',
|
115 | template: `
|
116 | <section><input type="text" [(ngModel)]="attribute"/></section>
|
117 | <section><button (click)="saveValue()">Save</button></section>
|
118 | `,
|
119 | })
|
120 | export class FooComponent {
|
121 |
|
122 | attribute;
|
123 |
|
124 | constructor(private storage:LocalStorageService) {}
|
125 |
|
126 | saveValue() {
|
127 | this.storage.store('boundValue', this.attribute);
|
128 | }
|
129 |
|
130 | }
|
131 | ````
|
132 |
|
133 | ------------
|
134 |
|
135 | #### Retrieve( key:`string` ):`any`
|
136 | > retrieve a value from the local storage
|
137 |
|
138 | ##### Params:
|
139 | - **key**: String. localStorage key.
|
140 |
|
141 | ##### Result:
|
142 | - Any; value
|
143 |
|
144 | ##### Usage:
|
145 | ````typescript
|
146 | import {Component} from '@angular/core';
|
147 | import {LocalStorageService} from 'ngx-webstorage';
|
148 |
|
149 | @Component({
|
150 | selector: 'foo',
|
151 | template: `
|
152 | <section>{{attribute}}</section>
|
153 | <section><button (click)="retrieveValue()">Retrieve</button></section>
|
154 | `,
|
155 | })
|
156 | export class FooComponent {
|
157 |
|
158 | attribute;
|
159 |
|
160 | constructor(private storage:LocalStorageService) {}
|
161 |
|
162 | retrieveValue() {
|
163 | this.attribute = this.storage.retrieve('boundValue');
|
164 | }
|
165 |
|
166 | }
|
167 | ````
|
168 |
|
169 | ------------
|
170 |
|
171 | #### Clear( key?:`string` ):`void`
|
172 |
|
173 | ##### Params:
|
174 | - **key**: *(Optional)* String. localStorage key.
|
175 |
|
176 | ##### Usage:
|
177 | ````typescript
|
178 | import {Component} from '@angular/core';
|
179 | import {LocalStorageService, LocalStorage} from 'ngx-webstorage';
|
180 |
|
181 | @Component({
|
182 | selector: 'foo',
|
183 | template: `
|
184 | <section>{{boundAttribute}}</section>
|
185 | <section><button (click)="clearItem()">Clear</button></section>
|
186 | `,
|
187 | })
|
188 | export class FooComponent {
|
189 |
|
190 | @LocalStorage('boundValue')
|
191 | boundAttribute;
|
192 |
|
193 | constructor(private storage:LocalStorageService) {}
|
194 |
|
195 | clearItem() {
|
196 | this.storage.clear('boundValue');
|
197 | //this.storage.clear(); //clear all the managed storage items
|
198 | }
|
199 |
|
200 | }
|
201 | ````
|
202 | ------------
|
203 |
|
204 | #### IsStorageAvailable():`boolean`
|
205 |
|
206 | ##### Usage:
|
207 | ````typescript
|
208 | import {Component, OnInit} from '@angular/core';
|
209 | import {LocalStorageService, LocalStorage} from 'ngx-webstorage';
|
210 |
|
211 | @Component({
|
212 | selector: 'foo',
|
213 | template: `...`,
|
214 | })
|
215 | export class FooComponent implements OnInit {
|
216 |
|
217 | @LocalStorage('boundValue')
|
218 | boundAttribute;
|
219 |
|
220 | constructor(private storage:LocalStorageService) {}
|
221 |
|
222 | ngOnInit() {
|
223 | let isAvailable = this.storage.isStorageAvailable();
|
224 | console.log(isAvailable);
|
225 | }
|
226 |
|
227 | }
|
228 | ````
|
229 |
|
230 | ------------
|
231 |
|
232 | #### Observe( key?:`string` ):`EventEmitter`
|
233 |
|
234 | ##### Params:
|
235 | - **key**: *(Optional)* localStorage key.
|
236 |
|
237 | ##### Result:
|
238 | - Observable; instance of EventEmitter
|
239 |
|
240 | ##### Usage:
|
241 | ````typescript
|
242 | import {Component} from '@angular/core';
|
243 | import {LocalStorageService, LocalStorage} from 'ngx-webstorage';
|
244 |
|
245 | @Component({
|
246 | selector: 'foo',
|
247 | template: `{{boundAttribute}}`,
|
248 | })
|
249 | export class FooComponent {
|
250 |
|
251 | @LocalStorage('boundValue')
|
252 | boundAttribute;
|
253 |
|
254 | constructor(private storage:LocalStorageService) {}
|
255 |
|
256 | ngOnInit() {
|
257 | this.storage.observe('boundValue')
|
258 | .subscribe((newValue) => {
|
259 | console.log(newValue);
|
260 | })
|
261 | }
|
262 |
|
263 | }
|
264 | ````
|
265 |
|
266 |
|
267 | ### <a name="s_sessionstorage">`SessionStorageService`</a>
|
268 | > The api is identical as the LocalStorageService's
|
269 |
|
270 | ### <a name="decorators">Decorators</a>
|
271 | --------------------
|
272 |
|
273 | ### <a name="d_localstorage">`@LocalStorage`</a>
|
274 | > Synchronize the decorated attribute with a given value in the localStorage
|
275 |
|
276 | #### Params:
|
277 | - **storage key**: *(Optional)* String. localStorage key, by default the decorator will take the attribute name.
|
278 | - **default value**: *(Optional)* Serializable. Default value
|
279 |
|
280 | #### Usage:
|
281 | ````typescript
|
282 | import {Component} from '@angular/core';
|
283 | import {LocalStorage, SessionStorage} from 'ngx-webstorage';
|
284 |
|
285 | @Component({
|
286 | selector: 'foo',
|
287 | template: `{{boundAttribute}}`,
|
288 | })
|
289 | export class FooComponent {
|
290 |
|
291 | @LocalStorage()
|
292 | public boundAttribute;
|
293 |
|
294 | }
|
295 | ````
|
296 |
|
297 | ------------
|
298 |
|
299 | ### <a name="d_sessionStorage">`@SessionStorage`</a>
|
300 | > Synchronize the decorated attribute with a given value in the sessionStorage
|
301 |
|
302 | #### Params:
|
303 | - **storage key**: *(Optional)* String. SessionStorage key, by default the decorator will take the attribute name.
|
304 | - **default value**: *(Optional)* Serializable. Default value
|
305 |
|
306 | #### Usage:
|
307 | ````typescript
|
308 | import {Component} from '@angular/core';
|
309 | import {LocalStorage, SessionStorage} from 'ngx-webstorage';
|
310 |
|
311 | @Component({
|
312 | selector: 'foo',
|
313 | template: `{{randomName}}`,
|
314 | })
|
315 | export class FooComponent {
|
316 |
|
317 | @SessionStorage('AnotherBoundAttribute')
|
318 | public randomName;
|
319 |
|
320 | }
|
321 | ````
|
322 |
|
323 | ### <a name="knownissues">Known issues</a>
|
324 | --------------------
|
325 |
|
326 | - *Serialization doesn't work for objects:*
|
327 |
|
328 | NgxWebstorage's decorators are based upon accessors so the update trigger only on assignation.
|
329 | Consequence, if you change the value of a bound object's property the new model will not be store properly. The same thing will happen with a push into a bound array.
|
330 | To handle this cases you have to trigger manually the accessor.
|
331 |
|
332 | ````typescript
|
333 | import {LocalStorage} from 'ngx-webstorage';
|
334 |
|
335 | class FooBar {
|
336 |
|
337 | @LocalStorage('prop')
|
338 | myArray;
|
339 |
|
340 | updateValue() {
|
341 | this.myArray.push('foobar');
|
342 | this.myArray = this.myArray; //does the trick
|
343 | }
|
344 |
|
345 | }
|
346 | ````
|
347 |
|
348 |
|
349 | ### <a name="modifBuild">Modify and build</a>
|
350 | --------------------
|
351 |
|
352 | `npm install`
|
353 |
|
354 | *Start the unit tests:* `npm run test`
|
355 |
|
356 | *Start the unit tests:* `npm run test:watch`
|
357 |
|
358 | *Start the dev server:* `npm run dev` then go to *http://localhost:8080/webpack-dev-server/index.html*
|
359 |
|
\ | No newline at end of file |