Creating Forms by Binding Fields to Items

    Let us start with a data model that has an item with a couple of properties. The item could be any item type, as described earlier.

    Next, you would design a form for editing the data. The FormLayout ( “FormLayout” is ideal for forms, but you could use any other layout as well.

    2. FormLayout form = new FormLayout();
    4. TextField nameField = new TextField("Name");
    5. form.addComponent(nameField);
    7. TextField ageField = new TextField("Age");
    8. form.addComponent(ageField);

    Then, we can bind the fields to the data as follows:

    1. // Now create the binder and bind the fields
    2. FieldGroup binder = new FieldGroup(item);
    3. binder.bind(nameField, "name");
    4. binder.bind(ageField, "age");

    The above way of binding is not different from simply calling setPropertyDataSource() for the fields. It does, however, register the fields in the field group, which for example enables buffering or validation of the fields using the field group, as described in .

    Next, we consider more practical uses for a FieldGroup.

    Using a FieldFactory to Build and Bind Fields

    Using the buildAndBind() methods, FieldGroup can create fields for you using a FieldGroupFieldFactory, but you still have to add them to the correct position in your layout.

    The bindMemberFields() method in FieldGroup uses reflection to bind the properties of an item to field components that are member variables of a class. Hence, if you implement a form as a class with the fields stored as member variables, you can use this method to bind them super-easy.

    The item properties are mapped to the members by the property ID and the name of the member variable. If you want to map a property with a different ID to a member, you can use the @PropertyId annotation for the member, with the property ID as the parameter.

    1. // Have an item
    2. PropertysetItem item = new PropertysetItem();
    3. item.addItemProperty("name", new ObjectProperty<String>("Zaphod"));
    4. item.addItemProperty("age", new ObjectProperty<Integer>(42));
    6. // Define a form as a class that extends some layout
    7. class MyForm extends FormLayout {
    8.     // Member that will bind to the "name" property
    9.     TextField name = new TextField("Name");
    11.     // Member that will bind to the "age" property
    12.     @PropertyId("age")
    14.     public MyForm() {
    15.         // Customize the layout a bit
    16.         setSpacing(true);
    18.         // Add the fields
    20.         addComponent(ageField);
    21.     }
    22. }
    24. // Create one
    25. MyForm form = new MyForm();
    27. // Now create a binder that can also creates the fields
    28. // using the default field factory
    29. FieldGroup binder = new FieldGroup(item);
    30. binder.bindMemberFields(form);
    32. // And the form can be used in an higher-level layout
    33. layout.addComponent(form);

    See the .

    Using a CustomComponent can be better for hiding the implementation details than extending a layout. Also, the use of the FieldGroup can be encapsulated in the form class.

    Consider the following as an alternative for the form implementation presented earlier:

    1. // A form component that allows editing an item
    2. class MyForm extends CustomComponent {
    3.     // Member that will bind to the "name" property
    4.     TextField name = new TextField("Name");
    6.     // Member that will bind to the "age" property
    7.     @PropertyId("age")
    8.     TextField ageField = new TextField("Age");
    10.     public MyForm(Item item) {
    11.         FormLayout layout = new FormLayout();
    12.         layout.addComponent(name);
    13.         layout.addComponent(ageField);
    14.         // Now use a binder to bind the members
    15.         FieldGroup binder = new FieldGroup(item);
    18.         setCompositionRoot(layout);
    19.     }
    20. }
    22. // And the form can be used as a component
    23. layout.addComponent(new MyForm(item));

    See the on-line example.

    Buffering Forms

    Just like for individual fields, as described in “Field Buffering”, a FieldGroup can handle buffering the form content so that it is written to the item data source only when commit() is called for the group. It runs validation for all fields in the group and writes their values to the item data source only if all fields pass the validation. Edits can be discarded, so that the field values are reloaded from the data source, by calling discard(). Buffering is enabled by default, but can be disabled by calling setBuffered(false) for the FieldGroup.

    See the .

    The BeanFieldGroup makes it easier to bind fields to a bean. It also handles binding to nested beans properties. The build a field bound to a nested bean property, identify the property with dot notation. For example, if a Person bean has a address property with an Address type, which in turn has a street property, you could build a field bound to the property with buildAndBind(“Street”, “address.street”).

    The input to fields bound to a bean can be validated using the Java Bean Validation API, as described in Bean Validation. The BeanFieldGroup automatically adds a BeanValidator to every field if a bean validation implementation is included in the classpath.

    Bean Validation

    Using bean validation requires an implementation of the Bean Validation API, such as Hibernate Validator ( hibernate-validator-4.2.0.Final.jar or later) or Apache Bean Validation. The implementation JAR must be included in the project classpath when using the bean validation, or otherwise an internal error is thrown.

    Bean validation is especially useful when persisting entity beans with the Vaadin JPAContainer, described in “Vaadin JPAContainer”.

    The validation constraints are defined as annotations. For example, consider the following bean:

    1. // Here is a bean
    2. public class Person implements Serializable {
    3.     @NotNull
    4.     @javax.validation.constraints.Size(min=2, max=10)
    5.     String name;
    7.     @Min(1)
    8.     @Max(130)
    9.     int age;
    11.     // ... setters and getters ...
    12. }

    For a complete list of allowed constraints for different data types, please see the .

    Validating a bean is done with a BeanValidator, which you initialize with the name of the bean property it should validate and add it the the editor field.

    In the following example, we validate a single unbuffered field:

    1. Person bean = new Person("Mung bean", 100);
    2. BeanItem<Person> item = new BeanItem<Person> (bean);
    4. // Create an editor bound to a bean field
    5. TextField firstName = new TextField("First Name",
    6.         item.getItemProperty("name"));
    8. // Add the bean validator
    9. firstName.addValidator(new BeanValidator(Person.class, "name"));
    11. firstName.setImmediate(true);

    In this case, the validation is done immediately after focus leaves the field. You could do the same for the other field as well.

    Bean validators are automatically created when using a BeanFieldGroup.