class Binding

A class that represents a property binding.

class Binding<T = any>

Description

A binding connects an object (an instance of ManagedObject) with one of the properties of one of its containing (attached) objects. Bindings can be used to update properties on the target object, keeping the bound property in sync with the original property.

For example, given an object A with property p, a binding can be used on an attached object B to update target property q. When the value of p changes, the same value is set on q immediately. This is considered a one-way data binding, since direct updates on property q don’t affect the source property p at all.

To make bindings work across a chain — or technically, a tree structure — of attached objects, bindings keep track of object attachments to the target object (i.e. object B) all the way up the chain, to find a matching source property. Therefore, a binding on C, itself attached from B, may also read property values from A.

Instead of a single source property, bindings can also specify a source property ‘path’ using dots to separate property names: a path of p.foo.bar first watches p, then (if p refers to an object) its property foo, and so on — going first up the tree structure to find the object containing p, and then down again to find the rest.

As a concrete example, a binding can be used to update the text property of a UILabel view, with the value of a string property labelText of the activity. Or perhaps the property name of a user object referenced by the activity (see example below). Whenever the data in the activity changes, so does the label text.

Creating bindings — To create a binding, use one of the bound() functions to bind a number, string, (negated) boolean, list, or a string composed using a format string and one or more embedded bindings, e.g. bound("anyValue"), bound.not("showList"), bound.string("labelText"), or bound.strf("Value: %i", "lines.count").

Binding to managed lists — ManagedList instances include special properties that may be referenced by a binding path. Use .count to bind to the list count, .#first and .#last to bind to the first and last item in the list, respectively.

Applying bindings — Include the result of bound() in the preset object or parameters passed to ui factory functions or preset of a custom ViewComposite, to add a bound property to a view, e.g. ui.label(bound.string("labelText")).

To apply a binding to any other managed object, use to the bindTo() method. This method can be used to bind a target property, or to call a function whenever the source value changes.

Adding filters — To convert the value of the original property, or to combine multiple bindings using boolean operations (and/or), use one of the Binding methods such as and(), select(), matches(), or strf().

Constructor

constructor(source?, defaultValue?)Creates a new binding for given property and default value; use bound() functions instead.

Type Members

type Binding.DebugEvent staticThe type of event that’s emitted by Binding.debugEmitter.
type Binding.ValidPathString staticA type that’s used to check binding path strings.
type Binding.StringFormatArgsFor staticA type that’s used to determine the arguments for bound.strf().

Static Members

Binding.debugEmitter staticEvent emitter used by Binding.debug().
Binding.limitTo(object, filter?) staticRestricts bindings that can be bound to (attached parent objects of) the specified object, if the object itself does not include a corresponding property.

Instance Members

bindTo(target, propertyOrFunction)Applies this binding to the specified target object.
asString(format?)Adds a filter, to convert the bound value to a string.
asNumber()Adds a filter, to convert the bound value to a number.
asList()Adds a filter, to make sure that the bound value is an iterable list.
asBoolean()Adds a filter, to convert the bound value to a boolean.
not()Adds a filter, to convert the bound value to a boolean, and negate it.
strf(format)Adds a filter, to include the bound value in a formatted string.
local(…type)Adds a filter, to use the current I18n provider to localize the bound value.
select(trueValue, falseValue?)Adds a filter, to use one of the provided values instead of the bound value.
else(falseValue)Adds a filter, to use the provided value instead of a bound value that’s equal to false.
matches(…values)Adds a filter, to compare the bound value and replace it with true or false.
equals(source)Adds a filter, to compare the bound value with another bound value.
and(source)Adds a filter, to perform a logical AND (i.e. &&) operation with another binding.
or(source)Adds a filter, to perform a logical OR (i.e. ||) operation with another binding.
debug()Adds a filter, to emit an event whenever the bound value changes.
toString()Returns a description of this binding, including its original source path, if any.
clone() protectedReturns a copy of this object.
isBindingA method that’s used for duck typing, always returns true.
[BindingOrValue.TYPE_CHECK]A method that’s used for type checking, doesn’t actually exist.