angular-property-binder

Bind property and keep safe the reference

Usage no npm install needed!

<script type="module">
  import angularPropertyBinder from 'https://cdn.skypack.dev/angular-property-binder';
</script>

README

angular-property-binder

Tiny library which help you to create reference variables and keep them intact.

Don't use you're controller as a MODEL - Best Practice.
Controllers should bind references to Models only (and call methods returned from promises)

Installation


bower install angular-property-binder
npm install angular-property-binder

Simply add:

<script type="text/javascript" src="dist/js/angular-property-binder.min.js">
</script>

to your HTML, load module ['PropertyBinder'] and then inject the binder service to your controller|service|factory|provider


angular.module('MyApp', ['PropertyBinder'])
    .controller('MyController', [
    'PropertyBinder.services.binder', 
    function(bind) { 
        ... 
    }])

API Reference


Angular Property Binder service provides easy to use and minimalistic chaining methods.
Here is the full list of accessible methods:

Service [PropertyBinder.services.binder]

binder( value )

Params:

  • value: String or Array. property name to bind.

Returns:

  • Object; the binder

Methods

from( scope, path )

Sets the source of the property to bind Mandatory

Params:

  • scope: Object. The source object containing the property to bind.
  • path: String or Array. The path to the targeted source.(optional)
    Useful when you wan't to create a reference on a nested property

Returns:

  • Object; the binder

to( scope )

Sets the target of the property to bind Mandatory

Params:

  • scope: Object. The targeted object.

Returns:

  • Object; the binder

apply( )

Applies the configured binding Mandatory

Returns:

  • Object; the binder

as( alias )

Sets the alias to use for the binding Optional

Params:

  • scope: Object or Array or String. The alias(es) to use.

Returns:

  • Object; the binder

onchange( callback )

Sets a onchange event Optional

Params:

  • callback: Function. The function called each time the property is updated from the created reference.

Returns:

  • Object; the binder

seal( )

Seals the binding. The next assignations will not work after this.

Returns:

  • Object; the binder

unseal( )

Unseals the binding. The next assignations will now work.

Returns:

  • Object; the binder

destroy( )

Delete the created reference


=======================

Basic usage: See the full documented example in example/modules/app/...

//cf example/modules/app/controllers/appTest.es6

angular.module('App')
    //you can use $scope or controllerAs methods
    .controller('App.controllers.appTest', [
    'PropertyBinder.services.binder', 
    'App.factories.users', 
    function(bind, userFactory){
        
        // old method - just create a reference with the factory property
        // this.users = userFactory.users;	
        // issue : the reference can be broken by many things

        bind('users'/*can take an array of properties*/)
            .from(userFactory)
            .to(this /*or $scope*/)
            .apply();

        console.log(this.users); //same as console.log(userFactory.users)

        bind('eyeColor')
            //avoid reference deleting
            //sample : get the eye color of the first user in the userFactory array
            .from(userFactory, 'users.0'/*path toward the nested property*/)
            .to(this)
            .apply();

        // the service can be used to create a reference on a primitive data type like integer or float
        bind('nbToLoad')
            .from(userFactory)
            .to(this)
            .apply()
            //bind an event triggered when the property is updated from this reference
            .onchange((newVal, oldVal) => {
                console.log('property updated', newVal, oldVal);
                userFactory.load();
            });

        // bind(['users','fu', 'bar']).from(userFactory).to(this /*or $scope*/).apply();

        // you can also give an alias to your property
        // in this case the property will be accessible by this.userAlias
        var binding = bind('users').as('usersAlias').from(userFactory).to(this /*or $scope*/).apply();
        // var binding = bind(['users','fu', 'bar']).as({ 'users':'usersAlias','fu':'fub', 'bar':'bars'}).from(userFactory).to(this /*or $scope*/).apply();
        // or
        // var binding = bind(['users','fu', 'bar']).as(['usersAlias','fub','bars']).from(userFactory).to(this /*or $scope*/).apply();

        // if you want to keep secure the factory data you can also seal the reference
        binding.seal();
        binding.unseal();

        // binding.destroy()

        // you can even bind a function in order to keep the scope
        bind('load').to(this).from(userFactory).apply();
        // this.load = userFactory.load; 

        userFactory.load();
    }]);

Other:


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();

}]);

Modify and build


npm install

To build the dev version just type: grunt es6 It will create js files from the es6 sources.

To build the dist version just type: grunt build It will generate and minify js files.