JBoss.orgCommunity Documentation

Chapter 9. Data Binding

9.1. Bindable Objects
9.2. Initializing a DataBinder
9.3. Creating Bindings
9.4. Specifying Converters
9.4.1. Registering a global default converter
9.4.2. Providing a binding-specific converter
9.5. Property Change Handlers

Errai's data binding module provides the ability to bind model objects to UI fields/widgets. The bound properties of the model and the UI components will automatically be kept in sync for as long as they are bound. So, there is no need to write code for UI updates in response to model changes and no need to register listeners to update the model in response to UI changes.

The data binding module is directly integrated with Chapter 10, Errai UI and Chapter 8, Errai JPA but can also be used as a standalone project in any GWT client application by simply inheriting the Data Binding GWT module:

Example 9.1. App.gwt.xml



<inherits name="org.jboss.errai.databinding.DataBinding" />

Objects that should participate in data bindings have to be marked as @Bindable and must follow Java bean conventions. All editable properties of these objects are then bindable to UI widgets.


Important

If you cannot annotate your classes with @Bindable , you can alternatively specify bindable types in your ErraiApp.properties using a whitespace-separated list of fully qualified class names: errai.ui.bindableTypes=org.example.Model1 org.example.Model2

An instance of DataBinder is required to create bindings. It can either be

injected into a client-side bean:

or created manually:

In both cases above, the DataBinder instance is associated with a new instance of the model (e.g. a new Customer object). A DataBinder can also be associated with an already existing object:

In case there is existing state in either the model object or the UI components before the they are bound, initial state synchronization can be carried out to align the model and the corresponding UI fields.

For using the model object's state to set the initial values in the UI:

For using the UI values to set the initial state in the model object:

Bindings can be created by calling the bind method on a DataBinder instance, thereby specifying which widgets should be bound to which properties of the model. It is possible to use property chains for bindings, given that all nested properties are of bindable types. When binding to customer.address.streetName , for example, both customer and address have to be of a type annotated with @Bindable .

After the call to dataBinder.bind() in the example above, the customer object's name property and the nameTextBox are kept in sync until either the dataBinder.unbind() method is called or the CustomerView bean is destroyed.

That means that a call to customer.setName() will automatically update the value of the TextBox and any change to the TextBox's value in the browser will update the customer object's name property. So, customer.getName() will always reflect the currently displayed value of the TextBox .

Errai has built-in conversion support for all Number types as well as Boolean and Date to java.lang.String and vice versa. However, in some cases it will be necessary to provide custom converters (e.g. if a custom date format is desired). This can be done on two levels.

In some cases keeping the model and the UI in sync is not enough. Errai's DataBinder allows for the registration of PropertyChangeHandlers for both specific properties or all properties of a bound model. This provides a uniform notification mechanism for model and UI value changes. PropertyChangeHandlers can be used to carry out any additional logic that might be necessary after a model or UI value has changed.