Added in deep compare option for bind and documented bind feature

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:<br/>
+**(1)** You can install angular-local-storage using 2 different ways:  
 **Git:**
-clone & build [this](https://github.com/grevory/angular-local-storage.git) repository<br/>
+clone & build [this](https://github.com/grevory/angular-local-storage.git) repository  
 **Bower:**
 ```bash
 $ bower install angular-local-storage
@@ -70,17 +70,16 @@ 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<br/>
+You could set a prefix to avoid overwriting any local storage variables from the rest of your app  
 **Default prefix:** `ls.<your-key>`
 ```js
 myApp.config(function (localStorageServiceProvider) {
   localStorageServiceProvider
     .setPrefix('yourAppName');
 });
 ```
-<<<<<<< HEAD
 ###setStorageType
-You could change web storage type to localStorage or sessionStorage<br/>
+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)<br/>
-**expiry:** number of days before cookies expire (0 = does not expire). **default:** `30`<br/>
+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<br/>
+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:<br/>
-**setItem** , default: `true`<br/>
+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.<br/>
-If local storage is not supported, use cookies instead.<br/>
+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.<br/>
-If local storage is not supported, use cookies instead.<br/>
+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.<br/>
+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.<br/>
-If local storage is not supported, use cookies instead.<br/>
+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.<br/>
-If local storage is not supported, use cookies instead.<br/>
-**Note:** Optionally takes a regular expression string and removes matching.<br/>
+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.<br/>
-**Note:** Typically used as a fallback if local storage is not supported.<br/>
+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.<br/>
+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.<br/>
+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.<br/>
+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:**<br/>
+**Deploy:**  
 Run the build task, update version before(bower,package)
 ```bash
 $ grunt dist

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

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++) {