bindable-object
v0.0.9
Published
Two-way data binding means linking properties of two separate objects - when one changes, the other will automatically update with that change. It enables much easier interactions between data models and UIs, among other uses outside of MVC.
Downloads
38
Readme
Fast data-binding library.
Two-way data binding means linking properties of two separate objects - when one changes, the other will automatically update with that change. It enables much easier interactions between data models and UIs, among other uses outside of MVC.
Example
var BindableObject = require("bindable-object");
var person = new BindableObject({
name: "craig",
last: "condon",
location: {
city: "San Francisco"
}
});
person.bind("location.zip", function(value) {
// 94102
}).now();
//triggers the binding
person.set("location.zip", "94102");
//bind location.zip to another property in the model, and do it only once
person.bind("location.zip", function (zip) {
console.log(zip); // 94102
}).now();
person.bind("name, last", function (fn, ln) {
console.log(fn, ln); // craig condon
}).now();
Installation
npm install bindable-object --save-exact
BindableObject(properties)
creates a new bindable object
value get(property)
Returns a property on the bindable object
var obj = new BindableObject({ city: { name: "SF" } });
console.log(obj.get("city")); // { name: "SF" }
console.log("no getter", obj.city); // { name: "SF" }
console.log(obj.get("city.name")); // SF
console.log("no getter", obj.city.name); // { name: "SF" }
set(property, value)
Sets a value to the bindable object
var obj = new BindableObject();
obj.set("city.name", "SF");
console.log(obj.get("city.name")); // SF
setProperties(properties)
sets multiple properties on the bindable object
var person = new BindableObject();
person.setProperties({
firstName: "Jon",
lastName: "Doe"
});
console.log(person.get("firstName"), person.get("lastName")); // Jon Doe
has(property)
Returns true if the bindable object has a given property
var obj = new BindableObject({ count: 0, male: false, name: "craig" });
console.log(obj.has("count")); // true
console.log(obj.has("male")); // true
console.log(obj.has("name")); // true
console.log(obj.has("city")); // false
listener on(event, callback)
adds a new listener to the bindable object
emit(event[,args...])
emits a new event
var person = new BindableObject();
person.on("blarg", function (arg1, arg2) {
console.log(arg1, arg2);
});
person.emit("blarg", "something!", "something again!!");
once(event, callback)
listens to one event, then disposes the listener.
var person = new BindableObject();
person.once("blarg", function (arg1, arg2) {
console.log(arg1, arg2);
});
person.emit("blarg", "something!", "something again!!");
person.emit("blarg", "never caught again!");
removeAllListeners([type])
returns all the listeners on the bindable object
binding bind(from, options)
options
- the options for the binding
to
- the property to bind to. Can be astring
,array
, orfunction
target
- the target bindable object. Default is selfmax
- max number of times to run the data-bindingwhen
- tests the data-bound value before settingmap
- transforms the data-bound valuebothWays
- makes the data-binding bi-directional.
var obj = new BindableObject({ name: "craig" });
// bind the name, but transform it to upper case
obj.bind("name", { to: "name2", map: function (name) {
return String(name).toUpperCase();
}}).now();
console.log(obj.get("name"), obj.get("name2"));
obj.set("name", "jeff");
console.log(obj.get("name"), obj.get("name2"));
binding.now()
Executes a binding now
var bindable = require("bindable");
var person = new BindableObject({ name: "jeff" });
person.bind("name", function (name, oldName) {
console.log("binding called, name is: ", name);
}).now();
// above is triggered
person.set("name", "joe");
binding.dispose()
Disposes a binding
var bindable = require("bindable");
var person = new BindableObject({ name: "jeff" });
var binding = person.bind("name", function (name, oldName) {
console.log("binding called, name is: ", name);
}).now();
binding.dispose();
person.set("name", "jake"); // binding not triggered
Events
Bindable objects emit a few events:
change:*
- emitted when a property changes on the bindable object. E.g:change:location.zip
.change
- emitted when any property changes on the bindable objectwatching
- emitted when a property is being watcheddispose
- emitted whendispose()
is called on a bindable object
var person = new BindableObject({ name: "jeff" });
person.on("change:name", function (newName) {
console.log("the name changed to", newName);
});
person.on("change", function (key, value) {
console.log("some value has changed: ", key, "=", value);
});
person.on("watching", function (property) {
console.log("watching ", property);
});
person.on("dispose", function () {
console.log("the object was disposed");
});
person.set("name", "james");
person.set("city", "sf");
person.bind("name", function(){}); // trigger watching
person.dispose();