ng-web-storage
An Angular module that gives you access to the browsers web storage (no fallbacks for now).
Table of contents:
- Get Started
- Configuration
- setPrefix
- setStorageCookie
- setStorageCookieDomain
- setNotify
- API Documentation
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:
... ... ...
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;
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;
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;
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;
API Documentation
Web Storage Service
The service returned by ngSessionWebStorageServiceProvider
supportsLocalStorage
Check if browser supports local web storage.
Returns: boolean
myApp;
supportsSessionStorage
Check if browser supports session web storage.
Returns: boolean
myApp;
supportsCookiesStorage
Check if browser supports cookies.
Returns: boolean
myApp;
notifyConfigs
Obtain notification configuration.
Returns: Object
myApp;
prefix
Obtain storage system prefix.
Returns: string
myApp;
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;
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;
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;
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;
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;
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;
keys
Return array of keys for web storage, ignore keys that not owned.
Returns: string[]|boolean
myApp;
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;
{{property}} update unbind
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;
Cookie Storage Wrapper
Deal with browser's cookies directly using ngCookieStorageService
.
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
daysToExpire?: number
- Optionally takes number of days until cookie expires
Returns: boolean
myApp;