diff --git a/README.md b/README.md index 20f3bd3..b9e8a2d 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,9 @@ An Angular module that gives you access to the browsers local storage, **v0.1.1* - [clearAll](#cookieclearall) ##Get Started -**(1)** You can install angular-local-storage using 2 different ways:
+**(1)** You can install angular-local-storage using 2 different ways: **Git:** -clone & build [this](https://github.com/grevory/angular-local-storage.git) repository
+clone & build [this](https://github.com/grevory/angular-local-storage.git) repository **Bower:** ```bash $ bower install angular-local-storage @@ -70,7 +70,7 @@ 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
+You could set a prefix to avoid overwriting any local storage variables from the rest of your app **Default prefix:** `ls.` ```js myApp.config(function (localStorageServiceProvider) { @@ -78,9 +78,8 @@ myApp.config(function (localStorageServiceProvider) { .setPrefix('yourAppName'); }); ``` -<<<<<<< HEAD ###setStorageType -You could change web storage type to localStorage or sessionStorage
+You could change web storage type to localStorage or sessionStorage **Default storage:** `localStorage` ```js myApp.config(function (localStorageServiceProvider) { @@ -89,8 +88,8 @@ myApp.config(function (localStorageServiceProvider) { }); ``` ###setStorageCookie -Set cookie options (usually in case of fallback)
-**expiry:** number of days before cookies expire (0 = does not expire). **default:** `30`
+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:** `'/'` ```js myApp.config(function (localStorageServiceProvider) { @@ -99,7 +98,7 @@ myApp.config(function (localStorageServiceProvider) { }); ``` ###setStorageCookieDomain -Set for cookie domain
+Set for cookie domain **No default value** ```js myApp.config(function (localStorageServiceProvider) { @@ -108,8 +107,8 @@ myApp.config(function (localStorageServiceProvider) { }); ``` ###setNotify -Send signals for each of the following actions:
-**setItem** , default: `true`
+Send signals for each of the following actions: +**setItem** , default: `true` **removeItem** , default: `false` ```js myApp.config(function (localStorageServiceProvider) { @@ -129,7 +128,7 @@ myApp.config(function (localStorageServiceProvider) { ``` ##API Documentation ##isSupported -Checks if the browser support the current storage type(e.g: `localStorage`, `sessionStorage`). +Checks if the browser support the current storage type(e.g: `localStorage`, `sessionStorage`). **Returns:** `Boolean` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -150,8 +149,8 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###set -Directly adds a value to local storage.
-If local storage is not supported, use cookies instead.
+Directly adds a value to local storage. +If local storage is not supported, use cookies instead. **Returns:** `Boolean` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -163,8 +162,8 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###get -Directly get a value from local storage.
-If local storage is not supported, use cookies instead.
+Directly get a value from local storage. +If local storage is not supported, use cookies instead. **Returns:** `value from local storage` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -176,7 +175,7 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###keys -Return array of keys for local storage, ignore keys that not owned.
+Return array of keys for local storage, ignore keys that not owned. **Returns:** `value from local storage` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -186,8 +185,8 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###remove -Remove an item from local storage by key.
-If local storage is not supported, use cookies instead.
+Remove an item from local storage by key. +If local storage is not supported, use cookies instead. **Returns:** `Boolean` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -199,9 +198,9 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###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.
+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` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -216,28 +215,52 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###bind -Bind $scope key to localStorageService. -**Usage:** `localStorageService.bind(scope, property, value[optional], key[optional])` -***key:*** The corresponding key used in local storage +Binds $scope or $rootScope key to an element stored in localStorageService. +**scope** : The location of the bound element, either $scope or $rootScope. +**scopeKey** : The name of the scoped element. E.g. for $scope.foo, this should be "foo". This doesn't need to be defined already. +**defaultValue** : [optional] If the value doesn't exist in localstorage, what should it default to? Defaults to null. +**localStorageKey** : [optional] The local storage key that maps to the bound value. By default, this is the same as scopeKey. +**useDeepCompare** : [optional] Should a more sensitve listener be used? Use true if you are binding an array of objects, or a similarly nested problem. Defaults to false. + **Returns:** deregistration function for this listener. + +#####A simple example binding $rootScope.property to a value. ```js -myApp.controller('MainCtrl', function($scope, localStorageService) { +myApp.controller('MainCtrl', function($rootScope, localStorageService) { //... localStorageService.set('property', 'oldValue'); - var unbind = localStorageService.bind($scope, 'property'); + var unbind = localStorageService.bind($rootScope, 'property'); //Test Changes - $scope.property = 'newValue1'; + $rootScope.property = 'newValue1'; console.log(localStorageService.get('property')) // newValue1; //unbind watcher unbind(); - $scope.property = 'newValue2'; - console.log(localStorageService.get('property')) // newValue1; + $rootScope.property = 'newValue2'; + console.log(localStorageService.get('property')) // still newValue1; //... }); ``` +#####A more complex example using the deeply nested comparison +```js +myApp.controller('MainCtrl', function($scope, localStorageService) { + //... + localStorageService.bind($scope, 'people', + [{name:"John", accountBalance:200},{name:"Mary", accountBalance:7000}], + 'members_account_balances', true); + //$scope.people is now bound to localstorage.members_account_balances + + //Test Changes + $scope.people[1].accountBalance = 6500; //this won't be detected if useDeepCompare == false + + console.log(localStorageService.get('members_account_balances')); // Mary's balance will now be 6500 + //... +}); +``` + + ###deriveKey -Return the derive key +Return the derive key **Returns** `String` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -249,7 +272,7 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###length -Return localStorageService.length, ignore keys that not owned. +Return localStorageService.length, ignore keys that not owned. **Returns** `Number` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -261,8 +284,8 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { ##Cookie Deal with browser's cookies directly. ###cookie.set -Directly adds a value to cookies.
-**Note:** Typically used as a fallback if local storage is not supported.
+Directly adds a value to cookies. +**Note:** Typically used as a fallback if local storage is not supported. **Returns:** `Boolean` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -274,7 +297,7 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###cookie.get -Directly get a value from a cookie.
+Directly get a value from a cookie. **Returns:** `value from local storage` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -286,7 +309,7 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###cookie.remove -Remove directly value from a cookie.
+Remove directly value from a cookie. **Returns:** `Boolean` ```js myApp.controller('MainCtrl', function($scope, localStorageService) { @@ -298,7 +321,7 @@ myApp.controller('MainCtrl', function($scope, localStorageService) { }); ``` ###clearAll -Remove all data for this app from cookie.
+Remove all data for this app from cookie. ```js myApp.controller('MainCtrl', function($scope, localStorageService) { //... @@ -324,7 +347,7 @@ Run the tests: ```bash $ grunt test ``` -**Deploy:**
+**Deploy:** Run the build task, update version before(bower,package) ```bash $ grunt dist diff --git a/src/angular-local-storage.js b/src/angular-local-storage.js index 6b00fec..fdfb754 100644 --- a/src/angular-local-storage.js +++ b/src/angular-local-storage.js @@ -367,7 +367,7 @@ angularLocalStorage.provider('localStorageService', function() { // Add a listener on scope variable to save its changes to local storage // Return a function which when called cancels binding - var bindToScope = function(scope, scopeKey, def, lsKey) { + var bindToScope = function(scope, scopeKey, def, lsKey, useDeepCompare) { if (!lsKey) { lsKey = scopeKey; } @@ -382,9 +382,15 @@ angularLocalStorage.provider('localStorageService', function() { $parse(scopeKey).assign(scope, value); - return scope.$watchCollection(scopeKey, function(newVal) { - addToLocalStorage(lsKey, newVal); - }); + if (!useDeepCompare) { + return scope.$watchCollection(scopeKey, function(newVal) { + addToLocalStorage(lsKey, newVal); + }); + } else { + return scope.$watch(scopeKey, function(newVal) { + addToLocalStorage(lsKey, newVal); + }, true); + } }; // Return localStorageService.length diff --git a/test/spec/localStorageSpec.js b/test/spec/localStorageSpec.js index 14551c5..f61c45e 100644 --- a/test/spec/localStorageSpec.js +++ b/test/spec/localStorageSpec.js @@ -319,8 +319,29 @@ describe('localStorageService', function() { expect($rootScope.property).toEqual(localStorageService.get('lsProperty')); })); + + it('should be able to bind a complicated object/array to scope', inject(function($rootScope, localStorageService) { + + + + localStorageService.set('members_account_balances', [{name:'John', accountBalance:200},{name:'Mary', accountBalance:7000}]); + + localStorageService.bind($rootScope, 'people', undefined, + 'members_account_balances', true); + + expect($rootScope.people).toEqual(localStorageService.get('members_account_balances')); + + $rootScope.people[1].accountBalance = 6500; //this may not be detected if useDeepCompare == false + + $rootScope.$digest(); + + expect($rootScope.people).toEqual(localStorageService.get('members_account_balances')); + + expect($rootScope.people[1].accountBalance).toEqual( + localStorageService.get('members_account_balances')[1].accountBalance); + })); - it('should be able to return it\'s owned keys amount', inject( + it('should be able to return its owned keys amount', inject( function(localStorageService, $window) { for(var i = 0; i < 10; i++) {