Skip to content

node_bind.md

Latest commit

 

History

History
152 lines (115 loc) · 4.64 KB

node_bind.md

File metadata and controls

152 lines (115 loc) · 4.64 KB
layout default
title Node.bind()
subtitle <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"http://prollyfill.org/">prollyfill</a" rel="nofollow">http://prollyfill.org/">prollyfill</a>
load_polymer true
imports
/elements/buildbot-list.html
feature
spec status code summary
None
<buildbot-list project="NodeBind"></buildbot-list>
Adds a new method to all DOM nodes, allowing a named property of the node to be bound to data.

{% include spec-header.html %}

Learn the tech

Why Node.bind()?

Node.bind() is a new method added to all DOM nodes which instructs them to bind the named property to the data provided. These allows applications to create a data model in JavaScript that DOM reacts to.

Basic usage

"Bind the value in obj.path.to.value to a TextNode's .textContent":

var obj = {
  path: {
    to: {
      value: 'hi'
    }
  }
};

var textNode = document.createTextNode('mytext');
textNode.bind('textContent', obj, 'path.to.value');

When the value in path.to.value changes, Node.bind() keeps .textContent up to date.

Binding types

The meaning of the binding name is interpreted by the node on which bind() is called.

  • Text node only handles bindings on the textContent property.
  • HTMLInputElement handles bindings on the value and checked properties as two-way.
  • All other elements handle bindings to attributes.

Text nodes

textNode.bind('textContent', someObj, 'path.to.value');

Instructs the Text node to make its textContent property dependent on the value someObj.path.to.value.

CaseResult
Initially String(someObj.path.to.value)
The value changes String(someObj.path.to.value)
The path is null, undefined, or unreachable "" (the empty string)

Element attribute values {#attributevalues}

myElement.bind('title', someObj, 'path.to.value');

Instructs the element to make the value its title attribute dependent on the value someObj.path.to.value.

CaseResult
Initially String(someObj.path.to.value)
The value changes String(someObj.path.to.value)
The path is null, undefined, or unreachable "" (the empty string)

Element attribute presence {#attributepresence}

myElement.bind('hidden?', someObj, 'path.to.value');

Instructs the element add/remove its hidden attribute based on the truthiness of someObj.path.to.value.

CaseResult
Initially "" (the empty string) if someObj.path.to.value is reachable and truthy
The value changes "" (the empty string) if someObj.path.to.value is reachable and truthy
Other cases The attribute is removed from the element

Input element value and checked properties {#inputelements}

value

myValueInput.bind('value', someObj, 'path.to.value');

Instructs the input to ensure its value property is equal to String(someObj.path.to.value). The binding is two-way. Upon binding, if the path is reachable, value is set to the path value. If the path is unreachable but can be made reachable by setting a single property on the final object, the property is set to value.

checked

myCheckboxOrRadioInput.bind('checked', someObj, 'path.to.value');

Instructs the input to ensure its checked property is equal to Boolean(someObje.path.to.value). The binding is two-way. Upon binding, if the path reachable, checked is set to the path value. If the path is unreachable but can be made reachable by setting a single property on the final object, the property is set to checked.

Custom element bindings

Custom Elements may choose to interpret bindings as they wish. They do this by overriding the bind() method.

MyFancyHTMLWidget.prototype.bind = function(name, obj, path) {
  if (name == 'myBinding')
    // interpret the binding meaning
  else
    HTMLElement.prototype.bind.call(this, name, obj, path);
};

If the element does not handle the binding, it should give its super class the opportunity to by invoking its bind() method.