Introduction
Bindings can define methods and properties on a bound element using the implementation tag. A binding implementation provides a new set of methods and properties that can be invoked directly from the bound element.
The methods and properties of an implementation can be defined declaratively using method and property tags in XML, or an external implementation (e.g., a binary implementation) can be specified using the src attribute. When the src attribute is specified, any children of the implementation element are ignored.
Methods
Methods are defined using the method element. The name given on the tag using the name attribute is the name that can be used to invoke the method on the element. A method with parameters specifies those parameters and their names with parameter elements declared underneath the method element.
The implementation of the method is contained inside a body element. The parameters specified are bound to their names in the method body.
<method name="scrollToIndex">
<parameter name="index"/>
<body>
<![CDATA[
if (index < 0)
return;
...
]]>
</body>
</method>
Properties
Properties can also be defined on the bound element using property tags. There are two basic types of properties. The first type of property is a raw value that is set directly on the element itself. The second type of property is one that defines functions that are invoked when the property is either retrieved or set. These functions are called getters and setters in XBL.
For properties with raw values, an initial value can be specified as a child of the property tag. The script is evaluated at the time of binding attachment and the resulting value is stored on the element. It can be assumed that the anonymous content of the binding has been fully constructed, although the bindingattached event will not have fired. Property initialization always takes place after content generation but before the firing of a binding attachment event, since the bindingattached handler needs to be able to assume that all properties will be accessible on the binding.
Properties with getters and setters can define them using onget and onset attributes, or using the more verbose getter and setter elements. If both the attribute form and the element form are used to specify a getter or setter, then the element form is ignored.
A getter contains script whose return value is handed back when the property is requested. A setter contains a script that is invoked when a new value is assigned to the property. In script, the word val is used to represent the new value.
Properties can be designated as constant using the readonly attribute. When set to true, the property's value cannot be altered. If a property is readonly and a setter is defined, then the setter is ignored.
Properties also support a shorthand syntax for defining getters and setters that forward requests or assignments to an anonymous content element. The element attribute specifies the ID of anonymous content underneath the bound element that should be used when obtained the property or setting the property.
On the anonymous content element, the property can be obtained either from an attribute on the element or from a property on the element. The property attribute's value specifies the name of a property to use on the anonymous content element. The attribute attribute specifies the name of an attribute to use on the anonymous content element. If either of these attributes is specified on the property element, then any defined getters and setters are ignored. A raw initial value is also ignored. If both a property and attribute are specified, then the property takes precedence and the attribute is ignored.
Inheritance of Implementations
When two bindings in an inheritance chain both supply implementations, the derived binding's implementation inherits from the base binding's implementation. Method and property lookups are dynamic. Without disambiguating, if two bindings define the same method or property, then the most derived binding's method or property will be used.
Because bindings extend DOM elements, they can override any built-in methods or properties on the DOM element. For example, a binding could override the setAttribute method on Element or the retrieval of the value property for an HTMLInputElement.
The following is currently not implemented in Mozilla, it seems. See bug #373652 for some details.
Implementations can be named using a name attribute specified on the implementation element. When an implementation has a name, that name can be used to disambiguate the desired method or property.
For example, given a binding with an implementation ColorPickerGrid that derives from an implementation ColorPicker where the two implementations both specify the setColor method, a caller could invoke ColorPicker's method with the following syntax:
... // myElement is a ColorPickerGrid myElement.ColorPicker.setColor(); // Calls the ColorPicker method. myElement.setColor(); // Calls the ColorPickerGrid method. ...
In addition to being able to specifically name a base class, the name baseBinding can be used to specify the method or property on the base binding without necessarily knowing what the base class is. This situation can occur when bindings implicitly inherit, e.g., through the use of addBinding.
myElement.baseBinding.setColor(); // Calls the ColorPicker method.