JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Bind.js

    bind.js - simple two way data binding to HTML and callbacks
    Filed under  › 

    • 🔾29%Overall
    • 693
    • 39.3 days
    • 🕩62
    • 👥5

    Bind.js

    Two way data binding for HTML and JavaScript (with node.js compatibility) with additional support for transforming data before it arrives in the DOM.

    npm version Coverage Status

    Demos

    Prerequisites

    setters/gettings, fn.bind, qSA (if using selectors), getOwnPropertyNames.

    Usage

    Create a new Bind based on an object and a mapping. The mapping uses a key/value pair of property path to handler. The handler can be a CSS selector (and thus updates the DOM) or a callback.

    There is also an advanced value that allows finer grain control over the binding (seen in the skills value in the example below).

    Browser version can be downloaded from releases or via a CDN like unpkg: https://unpkg.com/bind.js/dist/bind.min.js

    The node version can be installed using npm install -S bind.js.

    Example (JS Bin)

    var player = Bind({
      name: '@rem',
      score: 11,
      location: {
        city: 'Brighton',
        country: 'England'
      },
      skills: [
        'code',
        'chicken',
        'shortness'
      ]
    }, {
      score: '#score',
      name: '#name',
      'location.city': function (city) {
        alert(this.name + "'s city is " + city);
      },
      skills: {
        dom: '#skills',
        transform: function (value) {
          return '<li>' + this.safe(value) + '</li>';
        },
      }
    });
    
    document.querySelector('form').onsubmit = function (event) {
      event.preventDefault();
      player.skills.push(document.querySelector('#newSkill').value);
      this.reset();
    };
    

    Notice that in the second argument to Bind the mapping key is a path to the object property separated by a . period: 'location.city': function.

    Mapping values

    Mapping values can be:

    • String: a CSS expression
    • Function: a callback that receives the new value
    • Object: see below

    If the mapping value is an object, all the following properties are supported:

    • dom: a string CSS expression
    • callback: a function
    • transform: a function that receives the new value, and returns the HTML that will be set to the DOM.
    • parse: a function that receives the changed value from the DOM and returns the value that will be set in the JavaScript object

    Note that the transform function is applied to array elements when mapped to an array, and so does not receive the entire array. This is to allow control over updating lists in the DOM (see the example above).

    Arrays

    Individual array elements can be also mapped using the dot notation and the index in the array.

    In the example below, when the first cat name in the array changes, it will update the DOM.

    var data = Bind({
      cats: ['ninja', 'missy', 'dizzy']
    }, {
      cats: {
        dom: 'ul',
        transform: function (name) {
          return '<li>' + name + '</li>';
        }
      },
      'cats.0': '#first-cat'
    });
    
    // later let's add Sam to the cats
    data.cats.unshift('sam');
    

    Using the DOM to inform values

    If you want the DOM to drive the initial values of the bind object, then you'll need to set the JavaScript property value to null and it will read the value from the DOM at startup:

    var data = Bind({
      price: null
    }, {
      price: '.price',
    });
    

    Now in the HTML:

    <p class="price">£10.50</p>
    

    Now data.price has the value of £10.50. If you wanted this to be a float instead, you would use the parse and transform methods:

    var data = Bind({
      price: null
    }, {
      price: {
        dom: '.price',
        parse: function (v) {
          return parseFloat(v.replace(/^£/, ''), 10);
        },
        transform: function (v) {
          return '£' + v.toFixed(2);
        }
    });
    

    Now data.price is 10.5, and when the value is changed to data.price = 11.5, the DOM is updated to £11.50.

    Restrictions

    Deleting primitive property

    There's no handling deleted primitive properties. Once it is deleted, if it's added back in again, it can't be tracked:

    data.me.score++; // updates element#score
    delete data.me.score;
    data.me.score = 1; // does nothing
    
    // A work around is to restore the property object, the following
    // re-uses the bind map, and updates element#score again
    data.me = {
      score: 1,
      // ... etc
    };
    

    Events at the root object

    This isn't currently supported, but could be implemented with a special mapping - I'm open to suggestions here.

    Otherwise, the object can be nested and callbacks be bound to the first depth property (as seen in the forms example)

    Exporting

    If the original, unbound object is needed, a utility function is available on the root object:

    var copy = data.__export();
    

    License

    MIT / http://rem.mit-license.org

    Show All