ng-web-storage

v0.3.1

Published

2 years ago

An Angular module that gives you access to the browsers local storage

Downloads

0High
0Medium
0Low

ealves-pt

AngularJS local storage

ng-web-storage

An Angular module that gives you access to the browsers web storage (no fallbacks for now).

Get Started

(1) You can install ng-web-storage using 2 different ways: Git: clone & build this repository Bower:

$ bower install ng-web-storage --save

npm:

$ npm install ng-web-storage

(2) Include ng-web-storage.js (or ng-web-storage.min.js) from the dist directory in your index.html, after including Angular itself.

(3) Add 'ngWebStorageModule' 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/ng-web-storage.min.js"></script>
    ...
    <script>
        var myApp = angular.module('myApp', ['ngWebStorageModule']);

    </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 (ngWebStorageServiceProvider) {
  ngWebStorageServiceProvider
    .setPrefix('yourAppName');
});

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 (ngWebStorageServiceProvider) {
  ngWebStorageServiceProvider
    .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 (ngWebStorageServiceProvider) {
  ngWebStorageServiceProvider
    .setStorageCookieDomain('<domain>');
});

For local testing (when you are testing on localhost) set the domain to an empty string ''. Setting the domain to 'localhost' will not work on all browsers (eg. Chrome) since some browsers only allow you to set domain cookies for registry controlled domains, i.e. something ending in .com or so, but not IPs or intranet hostnames like localhost.

setNotify

Send signals for each of the following actions: setItem , default: true removeItem , default: false

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

API Documentation

Web Storage Service

The service returned by ngSessionWebStorageServiceProvider

supportsLocalStorage

Check if browser supports local web storage. Returns: boolean

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

supportsSessionStorage

Check if browser supports session web storage. Returns: boolean

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

supportsCookiesStorage

Check if browser supports cookies. Returns: boolean

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

notifyConfigs

Obtain notification configuration. Returns: Object

myApp.controller('MainCtrl', function($scope, ngWebStorageService) {
  //...
  if(ngWebStorageService.notifyConfigs.setItem) {
    //...
  }
  if(ngWebStorageService.notifyConfigs.removeItem) {
    //...
  }
  //...
});

prefix

Obtain storage system prefix. Returns: string

myApp.controller('MainCtrl', function($scope, ngWebStorageService) {
  //...
  var prefix = ngWebStorageService.prefix;
  //...
});

deriveQualifiedKey

Build a key to be used by the system. Params: key: string - Key to be used in the storage Returns: string - Full key used by the system

myApp.controller('MainCtrl', function($scope, ngWebStorageService) {
  //...
  function getFullKey(key) {
    return ngWebStorageService.deriveQualifiedKey(key);
  }
  //...
});

notify

Broadcast storage events through $rootScope. Params: type: number - notification type (0-'warning', 1-'error', 2-'setitem', 3-'removeitem') message: string - message to broadcast

myApp.controller('MainCtrl', function($scope, ngWebStorageService) {
  //...
  function notifyError(message) {
    return ngWebStorageService.notify(1, message);
  }
  //...
});

Storage Wrappers

There are three wrappers for storage: ngSessionWebStorageService, ngLocalWebStorageService and ngCookieStorageService. All share the following API to interact with session, local and cookie storage respectively. We will use ngSessionWebStorageService in the next examples.

isStorageSupported

Checks if the browser support the specific storage type.
Returns: boolean

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

get

Directly get a value from web storage. No fallback exists at the moment. Params: key: string - The key used in web storage Returns: string|boolean|Object

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

remove

Remove an item(s) from web storage by key. No fallback exists at the moment. Params: ...keys: string - List of keys used in web storage Returns: boolean

myApp.controller('MainCtrl', function($scope, ngSessionWebStorageService) {
  //...
  function removeItem(key) {
   return ngSessionWebStorageService.remove(key);
  }
  //...
  function removeItems(key1, key2, key3) {
   return ngSessionWebStorageService.remove(key1, key2, key3);
  }
});

Web Storage Wrappers

There are two web storage services: ngSessionWebStorageService and ngLocalWebStorageService. Both share the following API to interact with session and local storage respectively. We will use ngSessionWebStorageService in the next examples.

set

Directly set a value to web storage. No fallback exists at the moment. Params: key: string - Key to be used in web storage val: string|number|boolean|Object - Value to be stored Returns: boolean

myApp.controller('MainCtrl', function($scope, ngSessionWebStorageService) {
  //...
  function submit(key, val) {
   return ngSessionWebStorageService.set(key, val);
  }
  //...
});

keys

Return array of keys for web storage, ignore keys that not owned. Returns: string[]|boolean

myApp.controller('MainCtrl', function($scope, ngSessionWebStorageService) {
  //...
  var lsKeys = ngSessionWebStorageService.keys();
  //...
});

bind

Bind $scope key to ngSessionWebStorageService.
Usage: ngSessionWebStorageService.bind(scope, property, defaultValue?, lsKey?)
Params: scope: $rootScope|$scope - scope to bind property: string - property on the scope to watch defaultValue?: string|number|boolean|Object - default value if not in local storage lsKey?: string - key in local storage if different from the scope property Returns: deregistration function for this listener.

myApp.controller('MainCtrl', function($scope, ngSessionWebStorageService) {
  //...
  ngSessionWebStorageService.set('property', 'oldValue');
  $scope.unbind = ngSessionWebStorageService.bind($scope, 'property');

  //Test Changes
  $scope.update = function(val) {
    $scope.property = val;
    $timeout(function() {
      alert("localStorage value: " + ngSessionWebStorageService.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>

clearAll

Remove all data for this app from web storage. No fallback exists at the moment. Params: regex?: Regex - Optionally takes a regular expression string and removes matching. Returns: boolean

myApp.controller('MainCtrl', function($scope, ngSessionWebStorageService) {
  //...
  function clearNumbers() {
   return ngSessionWebStorageService.clearAll(/^\d+$/);
  }
  //...
  function clearAll() {
   return ngSessionWebStorageService.clearAll();
  }
});

Cookie Storage Wrapper

Deal with browser's cookies directly using ngCookieStorageService.

set

myApp.controller('MainCtrl', function($scope, ngCookieStorageService) {
  //...
  function submit(key, val) {
   return ngCookieStorageService.set(key, val, 1);
  }
  //...
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ng-web-storage

Table of contents:

Get Started

Configuration

setPrefix

setStorageCookie

setStorageCookieDomain

setNotify

API Documentation

Web Storage Service

supportsLocalStorage

supportsSessionStorage

supportsCookiesStorage

notifyConfigs

prefix

deriveQualifiedKey

notify

Storage Wrappers

isStorageSupported

get

remove

Web Storage Wrappers

set

keys

bind

clearAll

Cookie Storage Wrapper

set