angular-property-binder - npm Package Compare versions

Comparing version 0.1.5 to 0.1.6

package.json

 {
   "name": "angular-property-binder",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Bind property and keep safe the reference",
@@ -5,0 +5,0 @@ "keywords": [

README.md

 angular-property-binder
 =======================
 
-Tiny library which help you to create reference variables and keep them intact.
+Tiny library which help you to create reference variables and keep them intact. 
+  
+Don't use you're controller as a MODEL - [Best Practice](http://toddmotto.com/rethinking-angular-js-controllers/).  
+*Controllers should bind references to Models only (and call methods returned from promises)*
 
@@ -11,5 +14,6 @@ ### Installation
 
+
 Simply add:
 
-````
+````html
 <script type="text/javascript" src="dist/js/angular-property-binder.min.js">
@@ -20,16 +24,110 @@ </script>
 
-````
+````javascript
+
 angular.module('MyApp')
     .controller('MyController', [
     'PropertyBinder.services.binder', 
-    function(binder) { 
+    function(bind) { 
         ... 
     }])
+
 ````
 
-### Usage 
----------
+### API Reference
+------------
 
-see the documented example in `example/modules/app/controllers/appTest.es6`
+Angular Property Binder service provides easy to use and minimalistic chaining methods.  
+Here is the full list of accessible methods:
 
+##### **@service** **[Property.binder.binder]*** binder(property)  
+**param** ***property*** {**Array**|**String**} property name to bind  
+
+=======================
+
+##### **@method** ***from***(scope, path)  
+**@param** ***scope*** {**Object**|**Array**} source object containing the property to bind  
+**@param** ***path*** {**String**|**Array**} **[OPTIONAL]** path to the targeted source. Useful when you wan't to create a reference on a nested property  
+
+=======================
+
+##### **@method** ***to***(scope)  
+**@param** ***scope*** {**Object**|**Array**} target object  
+
+=======================
+
+##### **@method** ***as***(alias)  
+**@param** ***alias*** {**Object**|**Array**|**String**} alias(es) for property  
+
+=======================
+
+##### **@method** ***onchange***(callback) | adds a onchange event callback to the binding  
+**@param** ***callback*** {**Function**} function called each time the property is updated from the created reference  
+
+=======================
+
+##### **@method** ***seal***() | seals the binding. the assignations will not work after that  
+
+=======================
+
+##### **@method** ***unseal***()  
+
+=======================
+
+##### **@method** ***destroy***()  
+
+=======================
+
+Basic samples:
+````javascript
+
+var app = angular.module('app', ['PropertyBinder']);
+app.factory('app.factories.user', function() {
+	return {
+		authenticate: function() {/**/},
+		update: function() {/**/},
+		register: function() {/**/},
+		user: {
+			name: 'Jack',
+			firstname: 'Bar',
+			location: {
+				city: 'Fu',
+				country: 'FuBar'
+			}
+		}
+	};
+});
+	
+app.controller('app.controllers.sample', [
+	'$scope',
+	'app.factories.user', 
+	'PropertyBinder.services.binder', 
+function($scope, userFactory, bind) {
+
+	bind('user').from(userFactory).to($scope).apply();
+	console.log($scope.user.firstname); // "Bar"
+
+	var binding = bind('firstname').as('userName').to($scope).from(userFactory, ['user']).apply();
+	console.log($scope.userName); // "Bar"
+	$scope.userName = 'FuFuBarBar';
+	console.log($scope.userName, userFactory.user.firstname, $scope.user.firstname); // "FuFuBarBar", "FuFuBarBar", "FuFuBarBar"
+
+	binding.seal();
+	$scope.userName = 'Bar'; //it will not work
+	console.log($scope.userName, userFactory.user.firstname, $scope.user.firstname); // "FuFuBarBar", "FuFuBarBar", "FuFuBarBar"
+	$scope.user.firstname = 'Bar';
+	console.log($scope.userName, userFactory.user.firstname, $scope.user.firstname); // "Bar", "Bar", "Bar"
+
+	binding.unseal();
+
+	bind(['city', 'country']).to($scope).from(userFactory, 'user.location').apply();
+
+	bind('register').from(userFactory).to($scope).apply(); //similar to $scope.register = userFactory.bind(userFactory);
+
+	binding.destroy();
+
+}]);
+
+````
+See the full documented example in `example/modules/app/controllers/appTest.es6`.
+
 ### Modify and build
@@ -36,0 +134,0 @@ --------------------

No alert changes

Improved metrics

Total package byte prevSize

23894

15.47%

Number of lines in readme file

142

222.73%

No dependency changes