angular-local-storage/README.md

angular-local-storage

An Angular module that gives you access to the browsers local storage, v0.1.1

##Table of contents:

• Configuration
• setPrefix
• setStorageType
• setStorageCookie
• setStorageCookieDomain
• setNotify
• Example
• API Documentation
• isSupported
• getStorageType
• set
• get
• keys
• remove
• clearAll

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

###setStorageType You could change web storage type to localStorage or sessionStorage
Default storage: localStorage

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setStorageType('sessionStorage');
});

###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 (localStorageServiceProvider) {
  localStorageServiceProvider
    .setStorageCookie(45, '<path>');
});

###setStorageCookieDomain Set for cookie domain
No default value

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setStorageCookieDomain('<domain>');
});

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

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

###Configuration Example Using all together

myApp.config(function (localStorageServiceProvider) {
  localStorageServiceProvider
    .setPrefix('myApp')
    .setStorageType('sessionStorage')
    .setNotify(true, true)
});

##API Documentation ##isSupported Checks if the browser support the current storage type(e.g: localStorage, sessionStorage). Returns: Boolean

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

###getStorageType Returns: String

myApp.controller('MainCtrl', function($scope, localStorageService) {
  //...
  var storageType = localStorageService.getStorageType(); //e.g localStorage
  //...
});

###set Directly adds a value to local storage.
If local storage is not supported, use cookies instead.
Returns: Boolean

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

###get Directly get a value from local storage.
If local storage is not supported, use cookies instead.
Returns: value from local storage

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

###keys Return array of keys for local storage, ignore keys that not owned. Returns: value from local storage

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

###remove Remove an item from local storage by key.
If local storage is not supported, use cookies instead.
Returns: Boolean

myApp.controller('MainCtrl', function($scope, localStorageService) {
  //...
  function removeItem(key) {
   return localStorageService.remove(key);
  }
  //...
});

###clearAll Remove all data for this app from local storage.
If local storage is not supported, use cookies instead.
Note: Optionally takes a regular expression string and removes matching.
Returns: Boolean

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

##Installation:

$ bower install angular-local-storage

Example use:

angular.module('yourModule', ['LocalStorageModule'])
.controller('yourCtrl', [
  '$scope',
  'localStorageService',
  function($scope, localStorageService) {
    // Start fresh
    localStorageService.clearAll();

    // Set a key
    localStorageService.set('Favorite Sport','Ultimate Frisbee');

    // Delete a key
    localStorageService.remove('Favorite Sport');
}]);

/*
To set the prefix of your localStorage name, you can use the setPrefix method
available on the localStorageServiceProvider
*/
angular.module('yourModule', ['LocalStorageModule'])
.config(['localStorageServiceProvider', function(localStorageServiceProvider){
  localStorageServiceProvider.setPrefix('newPrefix');
}]);

How to bind to a $scope variable:

Usage: localStorageService.bind(scope, scopeKey, def, lsKey);

// Example
$scope.anArtist = {'firstname':'Pablo', 'lastname':'Picasso'};

// Bind to local storage service
localStorageService.bind($scope, 'anArtist', $scope.anArtist, 'specialArtist');

// get bound data:
console.log(localStorageService.get('specialArtist'));

Check out the full demo and documentation at http://gregpike.net/demos/angular-local-storage/demo.html

##TO DO:

• Expand Readme

##Development: Clone the project:

$ git clone https://github.com/<your-repo>/angular-local-storage.git
$ npm install
$ bower install

Run the tests:

$ grunt test

Deploy:
Run the build task, update version before(bower,package)

$ grunt dist
$ git tag 0.*.*
$ git push origin master --tags