Property Binding

---

In this tutorial, a simple application that counts up and down by clicking buttons is created.

The complete source code is as follows:

Properties of components

Bender components can have properties to manage their state. A Bender property is similar to a Javascript object property, but has the additional benefit of being observable with a watch element so that changes can be triggered whenever the value of a property changes.

In this example, the main component has a count that maintains a count that can go up and down by using two buttons. The count is also displayed using roman numerals, using another property called roman.

A property is defined by adding a property child element to the component element, such as:

<property name="count" as="number" value="0"/>

The name attribute is mandatory and defines the name of the property. The value attribute defines a value for the property; here, the count will start at zero. Because attributes in XML are always text strings, the as attribute can give more information about how to interpret the value. Here, the count should be interpreted as a Javascript number and not a text string. Other values for as are string, boolean (a Javascript boolean value, which can be true or false), json (a Javascript boolean using JSON notation) and dynamic (a Javascript expression; this is the default.)

Making the count go up and down

The two buttons button-plus and button-minus will increase or decrease the count. In the same manner as in External Component, a watch is used to get pushed events from the buttons and modify the value of the count property accordingly:

<watch>
  <get component="button-plus" event="!pushed"/>
  <set property="count" value="this.properties.count + 1"/>
</watch>

The set element sets the value (which is similar to a property value) to the specified target (the count property in this sample.) The value is a Javascript expression in which this refers to the current component. this.properties is a dictionary of the properties of the component, so this.properties.count refers to the count property of the component.

Converting the count to a roman number

A second property, called roman, is defined as follows:

<property name="roman" value="flexo.to_roman(`count).toUpperCase()"/>

Notice that the value of this property is a Javascript expression, with one difference: the character ` is used to refer to other properties of the component. This has two effects:

1. it is a shortcut to writing this.properties.count;
2. it creates a watch to make sure that the value of roman is updated every time the value of count changes (for instance, when one of the buttons is pushed.)

This is called a property binding, as the the roman property is now bound to the count property.

The end result of this property definition is that every time count is set to a new number value, roman is set to its representation in roman numerals using the library function to_roman() of Flexo, and then converted to upper case.

Displaying the count value

The last step is now to display the value of the roman property in the view of the component. In Bender this can be done by creating a text element in the view, then setting up a watch so that when the roman property changes, the text element is updated with the new value. With a text binding, this can be done easily, as shown below:

<view xmlns:html="http://www.w3.org/1999/xhtml">
  <html:p>
    Number of clicks: `roman
   </html:p>
 </view>

Once again, notice the ` character that introduces the roman property.

Binding from other components

In this applications, only positive numbers are shown. This means that when the count is zero, it cannot go down any further, and the minus button needs to be disabled. Standard buttons in Bender have an enabled property, which is a boolean. To disable a button, this property is set to false; to enable a button, this property is set to true.

To prevent the count from going below zero, the enabled property of the minus button is bound to the count property of the main component:

 <component href="../lib/button.xml" id="button-minus" class="red">
   <property name="enabled" value="#sample`count &gt; 0"/>
   <view>
     -1
   </view>
 </component>

The enabled property of the minus button shows a more complex binding, as it is not bound to a property of its own, but of another component (here, the main component, which has the id sample.) When the property of a different component is referred to, the property name (including the backtick character) is preceded by the component id, itself introduced by the # mark.