JBoss.orgCommunity Documentation
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 9, Errai UI and Errai JPA but can also be used as a standalone project in any GWT client application by simply inheriting the Data Binding GWT module:
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.
Example 8.2. Customer.java
@Bindable
public class Customer {
...
private String name;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
...
}
An instance of
DataBinder
is required to create bindings. It can either be
injected into a client-side bean:
public class CustomerView {
@Inject
private DataBinder<Customer> dataBinder;
}
or created manually:
DataBinder<Customer> dataBinder = DataBinder.forType(Customer.class);
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:
DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject);
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:
DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject, InitialState.FROM_MODEL);
For using the UI values to set the initial state in the model object:
DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject, InitialState.FROM_UI);
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. Note that when using Errai UI these bindings are created automatically based on matching data-field and model property names.
public class CustomerView {
@Inject
private DataBinder<Customer> dataBinder;
private Customer customer;
private TextBox nameTextBox = new TextBox();
// more UI widgets...
@PostConstruct
private void init() {
customer = dataBinder
.bind(nameTextBox, "name")
.bind(idLabel, "id")
.getModel();
}
}
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
.
It's important to retrieve the model instance using dataBinder.getModel() before making changes to it as the data binder will provide a proxy to the model to ensure that changes will update the corresponding UI components.
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.
@DefaultConverter
public class MyCustomDateConverter implements Converter<Date, String> {
private static final String DATE_FORMAT = "YY_DD_MM";
@Override
public Date toModelValue(String widgetValue) {
return DateTimeFormat.getFormat(DATE_FORMAT).parse(widgetValue);
}
@Override
public String toWidgetValue(Date modelValue) {
return DateTimeFormat.getFormat(DATE_FORMAT).format((Date) modelValue);
}
}
All converters annotated with
@DefaultConverter
will be registered as global defaults calling
Convert.registerDefaultConverter()
. Note that the
Converter
interface specifies two type parameters. The first one represents the type of the model field, the second one the type held by the widget (e.g.
String
for widgets implementing
HasValue<String>
). These default converters will be used for all bindings with matching model and widget types.