Data Binding

Data binding is a technique that binds the GUI data to the model data, and thus reliving the programmers from the tedious task of transferring data from the model to the GUI and from the GUI back to the model.

Akrogen provides an experimental support for data binding which links a XUL control value to a Javascript variable. In the current version, only textbox and listbox provides data binding.

Textbox

The textBox holds a value. This value can be bound to a javascript string. Binding a XUL textbox value to a Javascript variable is very simple : all you have to do is to use a special syntax in the value attribute :

<textbox value="#[jsVar]" />

where jsVar denotes any JavaScript variable which must be already declared.

Once declared this way, any change in the JS variable will be immediately propaged to the textbox, and vice versa.

A complete example of how to use databinding with textBoxes is provided in the usesCases catalog in this component : Components/Model/Script/Binding/TextBox.ackcpt.xml

Checkbox

TODO

Radio

TODO

RadioGroup

TODO

Menulist

TODO

Tree

TODO

Listbox

The listBox holds a collection of objects. This collection can be bound to a Javascript Array. To bind a XUL listBox to a JavaScript array, you have to instrument the value attribute with the array name using this syntax

<listbox value="#[jsArray]" ... >

In order to use this array in the list columns, you have to define the var attribute which represents the contents of the current row. This technique is very similar to the one used in the JSF dataTable.

For example, let persons be a Javascript array holding a collection of (name, age) couples :

var persons = new Array();
persons.push(new Person('Franck', 25));
names.push(new Person('Victor', 35));

This array can then be used as a value for a listbox :

<listbox  value="#[persons]" var="person">
    <listhead>
        <listheader label="Name" />
                <listheader label="Age" />
    </listhead>
    <listcols>
        <listcol value="#[person.name]"/>
        <listcol value="#[person.age]"/>
    </listcols>
</listbox>

A complete example of how to use data binding with listBoxes is provided in the usesCases catalog in this component : the Components/Model/Script/Binding/ListBox.ackcpt.xml

Akrogen provides also a wrapper that can be used to simplify the handling of a listbox and it's model. To declare such a wrapper, you have to : 

<script type="text/javascript" src="/Scripts/commons/xul/model/ListboxDataModel.js" /> 
<script type="text/javascript" >
<![CDATA[
        var items = new Array();                        
        var itemsModel = new ListboxDataModel('listbox1', items);
]]>
</script>

The ListboxModelWrapper constructor takes two parameters :

  • A XUL listbox identifier.
  • A Javascript array variable which will be bound to the listbox.

This wrapper provides some helper methods, which are :

  • appendItem : appends an item to the collection.
  • removeSelectedItems : removes the selected items from the collection.
  • selectAllItems : selects all the rows of the listbox.
  • clearSelectionItems : cancels any selection.
  • getSelectedItems : returns a Javascript array containing all the selected items of the list.

    A complete example of how to use data binding and the wrapper class with listboxes is provided in the usesCases catalog in this component : the Components/Model/Script/Binding/ListboxWithDataModel.ackcpt.xml.