Let's say we have a Person model JavaBean that looks like this:

public class Person {
  private Long id;
  private String name;
  private String surname;   
  private String phone;

  public Long getId() {return id;}
  public void setId(Long id) {this.id = id;}
  
  public String getName() {return name;}
  public void setName(String name) {this.name = name;}
  
  public String getSurname() {return surname;}
  public void setSurname(String surname) {this.surname = surname;}
  
  public String getPhone() {return phone;}
  public void setPhone(String phone) {this.phone = phone;}
}

A typical form will be created and used like this:

...
private BeanFormWidget personForm;
private Person person;
...
protected void init() {
  ...
  personForm = new BeanFormWidget(Person.class);
  addWidget("personForm", personForm);

  personForm.addBeanElement("name", "#Name", new TextControl(new Long(3), null), true);
  personForm.addBeanElement("surname", "#Last name", new TextControl(), true);
  personForm.addBeanElement("phone", "#Phone no", new TextControl(), true);
  ...
  person = lookupPersonService().getSomePerson();
  personForm.readFromBean(person);
  ...
}
...

Note that here we basically do three things:

Now that we have created the form we show how to process events, validate and read the request data. The following example code should be in the same widget as the previous:

...
private void handleEventSave() {
  if (personForm.convertAndValidate()) {
   personForm.writeToBean(person);
   ...
   lookupPersonService()().savePerson(person);
  }
}
...

This code will execute if an event "save" comes and will do the following:

Note the use of the getValueByFullName() method. Form API contains several such methods (named *ByFullName()), which allow to access fields, controls and values using full dot-separated element names.

If you have a composite JavaBean (containing other JavaBeans) you may want to create a form with a similar structure. Let's say that our Person bean contains an Address under "address" JavaBean property:

...
personForm = new BeanFormWidget(Person.class);
addWidget("personForm", personForm);
...
BeanFormWidget addrForm = personForm.addBeanSubForm("address");
addrForm.addBeanElement("postalCode", "#Postal code", new TextControl(), true);
addrForm.addBeanElement("street", "#Street", new TextControl(), true);
...

Note that the fields will be available from the main form using a dot-separated name, e.g. String street = (String) personForm.getValueByFullName("address.street").

At the core of the data binding API lies the notion of controls (org.araneaframework.uilib.form.Control). Controls are the widgets that do the actual parsing of the request parameters and correspond to the controls found in HTML forms, like textbox, textarea, selectbox, button, ... Additionally controls also do a bit of validating the submitted data. For example textbox control validates the minimum and maximum string length, since the HTML tag can do the same. Programmer usually does not read values from Control directly, but from FormElement that takes care of converting value of Control to FormElement Data.

The following example shows how to create a control:

...
TextControl textBox = new TextControl(new Long(10), null);
...

This code will create a textbox with a minimal length of 10. Note that this code does not yet put the control to work, as controls are never used without forms, which are reviewed in the next section.

Follows a table of standard controls all found in org.araneaframework.uilib.form.control package:

SelectControl and MultiSelectControl deserve a special mention, as they need a bit more handling than the rest. The difference comes from the fact that we also need to handle the selectable options, which we refer to as DisplayItem. Each DisplayItem has a label, a string value and can be disabled. Disabled display items cannot be selected in neither select box nor multiselect box.

Both SelectControl and MultiSelectControl implement the DisplayItemContainer interface that allows to manipulate the DisplayItem:

interface DisplayItemContainer {
  void addItem(DisplayItem item);
  void addItems(Collection items);
  void clearItems();
  List getDisplayItems();
  int getValueIndex(String value);
}

In addition to this interface we also provide a DisplayItemUtil that provides some support methods on display items. These include the method addItemsFromBeanCollection that allows to add the items to a (multi)select control from a business method returning a collection of model JavaBean objects (which is one of the most common use cases). So a typical select control will be filled as follows:

SelectControl control = new SelectControl();
control.addItem(new DisplayItem(null, "- choice -"));
DisplayItemUtil.addItemsFromBeanCollection(
  control,
  lookupMyService().getMyItemCollection(),
  "value",
  "label");

Controls can also listen to user events. For example ButtonControl can react to an onClick event, while most others can react to an onChange event. The only thing needed to receive the control events is to register an appropriate event listener:

...
SelectControl selControl = new SelectControl();
FormElement selEl = form.addBeanElement("clientId", "#Client id", selControl, true);
selControl.addOnChangeEventListener(new OnChangeEventListener() {
  public void onChange() {
    //We convert and validate one element only as the rest of the form
    //might be invalid
    if (selEl.convertAndValidate()) {
      Long clientId = (Long) selEl.getValue();
      //Now we can use the client id to do whatever we want
      //E.g. update another select control
    }
  }
});
...

onChange events are also produced by text boxes and similar, so the user input can processed right after the user has finished it.

Though controls provide some amount of validation they are limited only to the rules that can be controlled on the client-side. To support more diverse rules Aranea has org.araneaframework.uilib.form.Constraint, that allows to put any logical and/or business validation rules. Typically constraints are used as follows:

...
myForm.addBeanElement("registration", "#Registration", new DateControl(), true);
myForm.getElement("registration").setConstraint(new AfterTodayConstraint(false));
...

The org.araneaframework.uilib.form.constraint.AfterTodayConstraint makes sure that the date is today or later, with the boolean parameter indicating whether today is allowed. The constraint will validate if the form or the element in question is validated (e.g. convertAndValidate() is called) and will show an error message to the user, if the constraint was not satisfied. The error message is customizable using localization and involves the label of the field being validated.

The following is a more complex example that shows how to use constraints that apply to more than one field, and how to combine constraints using logical expressions:

...
searchForm = new FormWidget();

//Adding form controls
searchForm.addElement("clientFirstName", "#Client first name", 
  new TextControl(), new StringData(), false);
searchForm.addElement("clientLastName", "#Client last name", 
  new TextControl(), new StringData(), false);

searchForm.addElement("clientAddressTown", "#Town", 
  new TextControl(), new StringData(), false);
searchForm.addElement("clientAddressStreet", "#Street", 
  new TextControl(), new StringData(), false);

//First searching scenario
AndConstraint clientNameConstraint = new AndConstraint();
clientNameConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientFirstName")));
clientNameConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientLastName")));

//Second searching scenario
AndConstraint clientAddressConstraint = new AndConstraint();
clientAddressConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientAddressTown")));
clientAddressConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientAddressStreet")));

//Combining scenarios
OrConstraint searchConstraint = new OrConstraint();    
searchConstraint.addConstraint(clientNameConstraint);
searchConstraint.addConstraint(clientAddressConstraint);

//Setting custom error message
searchConstraint.setCustomErrorMessage("Not enough data for search!");

//Setting constraint
searchForm.setConstraint(searchConstraint);

//Putting the widget
addWidget("searchForm", searchForm);    
...

The example use case is a two scenario search—either both client first name and client last name fields are filled in or both town and street address fields are filled in, otherwise an error message "Not enough data for search!" is shown. The constraints will be validated when convertAndValidate() method is called on searchForm. Note that the constraint is added to the form itself, rather than to its elements—this is a typical idiom, when the constraint involves several elements.

Table of standard Constraints.

There are two constraints that deserve a special mention. One of them is OptionalConstraint that will only let its subconstraint to validate the field, if the field has been submitted by user (it is very useful for instance when non-mandatory fields must nevertheless follow some pattern, whereas empty input should still be allowed).

The other constraint is called GroupedConstraint. It is useful in cases when different constraints should be activated depending on the particular state of the component (a typical use case is that some groups of fields are made mandatory in different states of document approval). The constraint is created using the ConstraintGroupHelper as follows:

...
ConstraintGroupHelper groupHelper = new ConstraintGroupHelper();
AndConstraint andCon = new AndConstraint();
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field1), "group1"));
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field2), "group1"));
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field3), "group2"));
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field4), "group2"));
form.setConstraint(andCon);

//Now only field1 and field2 will be required from user!
groupHelper.setActiveGroup("group1");
...

...
public class PersonIdentifierConstraint extends BaseFieldConstraint {
  public void validateConstraint() {
    if (!PersonUtil.validateIdentifier(getValue()) {
      addError("Field '" + getLabel() + "' is not a valid personal identifier");
    }
  }
}
...

The typical use of forms includes associating the form fields with JavaBean properties. However this is not always possible, since it is not feasible to make a JavaBean property for each and every form field. In such cases one may still want to use type conversion and data validation. To do that forms allow the org.araneaframework.uilib.form.Data and its subclasses (subclasses correspond to specific types) to be associated with the field:

...
personForm = new BeanFormWidget(Person.class);
addWidget("personForm", personForm);
...
personForm.addElement("numberOfChildren", "#No. of chidren",
  new NumberControl(), new LongData(), true);
...

In such a case one can retrieve the data directly from the field:

...
private void handleEventSave() {
  if (myForm.convertAndValidate()) {
    ...
    Long numberOfChildren = (Long) personForm.getValueByFullName("numberOfChildren");
    //Alternative:
    //FormElement nocEl = (FormElement) personForm.getElement("numberOfChildren");
    //Long numberOfChildren = (Long) nocEl.getValue();
    ...
  }
}
...

If there is no JavaBean to associate the form with org.araneaframework.uilib.form.FormWidget may be used instead of BeanFormWidget.

Note that the reason for existence of Data objects is that Java types correspond poorly to some restricted types—for instance enumerations, type encodings and collections container types (this problem is somewhat solved in Java 5, but Aranea is compatible with Java 1.3).

Table of Data types.

Finally Data constructor also accepts both a Class instance and a simple string. So if you have a custom datatype with an appropriate converter (see next section) you can just assign the data with the same type (in fact if you have your own converter the type doesn't matter that much, it will just allow some checks to be done on the programmer).

Converter sole purpose is conversion of values with one type to values of another type. Conventionally converter which convert() method accepts object of type A and returns object of type B is named AToBConverter. Converter from type B to type A is obtained with new ReverseConverter(new AToBConverter()).

public interface Converter extends Serializable, FormElementAware {
    public void setFormElementCtx(FormElementContext feCtx);
    public Object convert(Object data);
    public Object reverseConvert(Object data);
    public Converter newConverter();
}

Converters are used internally to convert Control values to values of FormElement Data and vice-versa. Converters are usually looked up from ConverterFactory, but each FormElement can be set explicit Converter by calling FormElement.setConverter(). Direction of Converter set this way should be from FormElement Control value type to FormElement Data type.

As already mentioned, form validation is mostly explicit. By default, the values will be just read from request without any parsing, conversion or validation. Validation will be performed after call to FormWidget.convertAndValidate().

It is also possible to configure forms to be validated in the background, as end-user is filling it. Background validation is enabled by calling FormWidget.setBackgroundValidation(true). This performs XMLHttp requests (using Aranea Action API) to server each time when user moves from changed form field to another. Background validation takes place on server-side and is implicit.

Produced form validation error messages are rendered by active FormElementValidationErrorRenderer implementation, which adheres to these methods:

public interface FormElementValidationErrorRenderer extends Serializable {

  void addError(FormElement element, String error);

  void clearErrors(FormElement element);

  String getClientRenderText(FormElement element);

}

The last method is used to provide the client-side script (together with <script>...</script> tags) that binds its validator with the given form element and updates error messages inside the <span> element of the given form element.

It is possible to choose between two bundled implementations — StandardFormElementValidationErrorRenderer, which is enabled by default, and LocalFormElementValidationErrorRenderer. The first one renders FormElement validation errors to standard MessageContext. The second bundled implementation renders the validation messages into the same HTML span element as input field (using the script returned by the getClientRenderText(FormElement) method).

FormElementValidationErrorRenderer default implementation can be switched by configuring the bean representing ConfigurationContext (named 'araneaConfiguration') to have entry with key 'uilib.widgets.forms.formelement.error.renderer' value set to desired FormElementValidationErrorRenderer instance:

<bean id="araneaConfiguration" singleton="false"
    class="org.araneaframework.uilib.core.StandardConfiguration">
  <property name="confEntries">
    <map>
      <entry key="uilib.widgets.forms.formelement.error.renderer"
        value="org.araneaframework.uilib.form.LocalFormElementValidationErrorRenderer"/>
    </map>
  </property>
</bean>

For the cases where validation errors should be rendered differently for just few elements, FormElement.setFormElementValidationErrorRenderer() method should be used.

Specifies form context for inner tags. Form view model and id are made accessible to inner tags as EL variables.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    ...  <!-- formElements, formElementLabels, ... --> ...
</ui:form>

Specifies form element context for inner tags. Must be surrounded by <ui:form> tag. Form element view model, id and value are made accessible to inner tags as EL variables.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:formElement id="username">
        ...
    </ui:formElement>
</ui:form>

Renders localizable label bound to form element. Rendered with HTML <span> and <label> tags.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:row>
        <ui:formElement id="username">
            <ui:cell>
                <ui:label/>
            </ui:cell>
        </ui:formElement>
    </ui:row>
</ui:form>

Renders localizable label (with HTML <span> and <label> tags).

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:row>
        <ui:cell>
            <ui:simpleLabel labelId="username.input.label" showMandatory="true" for="username"/>
        </ui:cell>
    </ui:row>
</ui:form>

Renders form buttons that represent ButtonControls. Either HTML <button> or <input type="button" ... > will be used for rendering.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:button id="loginButton"/>
</ui:form>

Renders HTML link that represents ButtonControl. HTML <a href="javascript:" ... > tag will be used for rendering. Default styleClass="aranea-link".

Registers a simple keyboard handler. Invokes a uiRegisterKeyboardHandler javascript. This is basically the same stuff as <ui:keyboardHandler> with a few modifications.

There is no scope attribute. Instead, the tag assumes that it is located inside a form, and takes the full id of that form as its scope.

As an alternative to specifying the handler attribute, you may specify a form element and a javascript event to invoke on that element. You specify the element by its id relative to the surrounding form. The event is given as a name of the javascript function to be invoked on the element. For example, if you specify the element as "someButton", and event as "click", then when the required keyboard event occurs, the following javascript will be executed:

var el = document.getElementById("<form-id>.someButton");
el.click();

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:eventButton id="btnLogin" eventId="login" labelId="button.login.enter"/>
    <ui:formKeyboardHandler fullElementId="btnLogin" key="enter"/>
</ui:form>

Same as <ui:formKeyboardHandlerTag> except key is already set to enter.

Same as <ui:formKeyboardHandlerTag> except key is already set to escape.

Form text input field, represents TextControl. It is rendered in HTML with <input type="text" ...> tag. Default styleClass="aranea-text".

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="someForm">
  <ui:formElement id="firstField">
     <!-- Renders input field binded to form's firstField element -->
     <ui:textInput/>
  </ui:formElement>
</ui:form>

Form text input field, represents AutoCompleteTextControl. It is rendered in HTML with <input type="text" ...> tag. Default styleClass="aranea-text". It is able to make background AJAX request to the server, fetching suggested completions to user input and displaying these to the user.

Form text input field, represents ComboTextControl. This is an input field combined with Select—it allows end-user to enter text into field or select some predefined value from provided list of values. It is rendered in HTML with <input type="text" ...> tag plus custom select component. Default styleClass="aranea-text".

Form text display field, represents TextControl. It is rendered in HTML with <span ...> tag. Default styleClass="aranea-text-display".

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="someForm">
  <ui:formElement id="firstField">
     <!-- Renders display field for form's firstField element -->
     <ui:textInputDisplay/>
  </ui:formElement>
</ui:form>

Form number input field, represents NumberControl. It is rendered in HTML with <input type="text" ...> tag. Default styleClass="aranea-number".

Form number display field, represents NumberControl. It is rendered in HTML with <span ...> tag. Default styleClass="aranea-number-display".

Form floating-point number input field, represents FloatControl. It is rendered in HTML with <input type="text" ...> tag. Default styleClass="aranea-float".

Form floating-point number display field, represents FloatControl. It is rendered in HTML with <span ...> tag. Default styleClass="aranea-float-display".

Form number input field, represents TextControl. It is rendered in HTML with <input type="password" ...> tag. Default styleClass="aranea-text".

Form text display field, represents DisplayControl, displays element value as String. It is rendered in HTML with <span ...> tag.

Puts form element value in page scope variable, represents DisplayControl. It does not output any HTML.

Form text input area, represents TextareaControl. It is rendered in HTML with <textarea ...> tag. Default styleClass="aranea-textarea".

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="someForm">
  <ui:formElement id="longLongText">
    <ui:cell>
      <ui:textarea rows="15" cols="150"/>
    </ui:cell>
  </ui:formElement>
</ui:form>

Form text input area, represents TextareaControl. It is rendered in HTML with <textarea ...> tag with styleClass="richTextEditor". The area is displayed as a rich text editor. The configuration of the editor is done via <ui:richTextAreaInit>. The tag shares all the attributes of the <ui:textarea> except the styleClass which cannot be set for this tag.

A tag for configuring the rich textareas. The tinyMCE WYSIWYG editor is attached to the textareas defined via <ui:richTextarea> . The configuration lets you choose the looks, buttons, functionality of the editor. See tinyMCE configuration reference for different configurable options.

The configuration is done via nesting key value pairs inside the <ui:richTextAreaInit>. For the key value pairs the <ui:attribute> tag is used. See the example for an overview.

The editor_selector and mode options are set by default and should not be changed. The default theme is "simple".

Important: the configuration should be done in the <head> section of the HTML document.

<ui:richTextAreaInit>
  <ui:attribute name="theme" value="advanced"/>
  <ui:attribute name="theme_advanced_buttons1" value="bold,italic,underline,separator,code"/>
  <ui:attribute name="theme_advanced_toolbar_location" value="top"/>
  <ui:attribute name="theme_advanced_toolbar_align" value="left"/>
  <ui:attribute name="theme_advanced_path_location" value="bottom"/>
</ui:richTextAreaInit>

Form text display area, represents TextareaControl. It is rendered in HTML with <span ...> tag. Default styleClass="aranea-textarea-display".

Represents a "hidden" form input element—HiddenControl. It is rendered in HTML with <input type="hidden" ...> tag.

Form checkbox input field, represents CheckboxControl. By default styleClass="aranea-checkbox". Rendered in HTML with <input type="checkbox" ...> tag.

Form checkbox display field, represents CheckboxControl. By default styleClass="aranea-checkbox-display". Rendered in HTML inside <span> tag.

Form file upload field, represents FileUploadControl.

<?xml version="1.0" encoding="UTF-8"?>
...
<ui:form id="uploadForm">
   <ui:row>
       <ui:cell styleClass="name">
           <ui:fileUpload id="file"/>
       </ui:cell>
   </ui:row>
</ui:form>
...

Form date input field, represents DateControl. Default styleClass="aranea-date".

Form date display field, represents DateControl. Default styleClass="aranea-date-display".

Form time input field, represents TimeControl. Default styleClass="aranea-time". HTML <select>s for easy hour/minute selection are rendered too, unless showTimeSelect attribute forbids it.

Form time display field, represents TimeControl. Default styleClass="aranea-time-display".

Form input field for both date and time, represents DateTimeControl. It is rendered as input fields for date and time + date picker and time picker (time picker can be switched off by setting showTimeSelect="false" if so desired).

Form display field for both date and time, represents TimeControl. Default styleClass="aranea-datetime-display".

Form dropdown list input field, represents SelectControl. Default styleClass="aranea-select", rendered with HTML <select ...> tag.

Form select display field, represents SelectControl. Default styleClass="aranea-select-display", rendered with HTML <span ...> tag.

Form list input field, represents MultiSelectControl. Default styleClass="aranea-multi-select", rendered with HTML <select multiple="true" ...> tag.

Form multiselect display field, represents MultiSelectControl. Default styleClass="aranea-multi-select-display", rendered with HTML <span ...> tag.

Form radioselect buttons field, represents SelectControl. Default styleClass="aranea-radioselect". It takes care of rendering all its elements; internally using <ui:radioSelectItemLabel> and <ui:radioSelectItem> tags.

Form radio button, represents one item from SelectControl. Default styleClass="aranea-radio". It will be rendered with HTML <input type="radio" ...> tag.

Form radio button label, represents label of one item from SelectControl. It will be rendered with HTML <span ...> tag.

Form multiselect checkbox field, represents MultiSelectControl. It takes care of rendering all its elements; internally using <ui:checkboxMultiSelectItemLabel> and <ui:checkboxMultiSelectItem> tags.

Form radio button, represents one item from MultiSelectControl. Default styleClass="aranea-multi-checkbox". It will be rendered with HTML <input type="checkbox" ...> tag.

Form checkbox label, represents label of one item from MultiSelectControl. It will be rendered with HTML <span ...> tag.

Depending whether form element boolean value is true or false display one or other content, represents DisplayControl. <ui:conditionFalse> and <ui:conditionFalse> tags must be used inside this tag to define alternative contents. This tag itself is not rendered.

The content of this tag will be displayed when form element of surrounding <ui:conditionalDisplay> was false. Tag has no attributes.

The content of this tag will be displayed when form element of surrounding <ui:conditionalDisplay> was true. Tag has no attributes.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="someForm">
  <ui:conditionalDisplay id="isActive">
    <ui:conditionTrue>
      <img src="red_flag.png"/>
    </ui:conditionTrue>
    <ui:conditionFalse>
      <img src="green_flag.png"/>
    </ui:conditionFalse>
  </ui:conditionalDisplay>
</ui:form>

Display form element value as list of strings, represents DisplayControl and requires that element value would be of type Collection.

Sometimes the type of FormElement is not known for sure when writing JSP (it could be textInput, floatInput, select, ...). For that purpose, FormElement that has some known identifier can be dynamically associated with some JSP tag in Java code and then rendered with <ui:automaticFormElement> tag which uses associated tag to render FormElement.

element.setProperty(FormElementViewSelector.FORM_ELEMENT_VIEW_SELECTOR_PROPERTY, new FormElementViewSelector(tag, attributes));
AutomaticFormElementUtil.setFormElementViewSelector(element, new FormElementViewSelector(tag, attributes));
AutomaticFormElementUtil.setFormElementTag(element, tag, attributes);

<?xml version="1.0" encoding="UTF-8"?>
<ui:formElement id="someForm">
  <ui:cell>
    <ui:automaticFormElement/>
  </ui:cell>
</ui:formElement>

Unlike usual forms, form lists are "lazy", from the point that they are tied to a model and update themselves according to it. To create a form list widget we pass it a model and a handler:

... 
  public void init() throws Exception {
    private FormListWidget personFormList;
    ...
    Map persons = lookupMyService().getPersons();

    personFormList = new BeanFormListWidget(
        new PersonFormRowHandler(),
        new MapFormListModel(persons),
        Person.class);

    addWidget("personFormList", personFormList);
  }
...

Note here that we have tied the form list to the model that uses a Map as the underlying storage. When we update that map, the form list will also be updated. Note also that the form list widget is associated with the Person bean class, which can be used to manipulate the beans under the model.

However this code doesn't yet tell us much. The bulk of the custom logic of the form lists is hidden in the PersonFormRowHandler class. Let's inspect it step by step.

Every form row handler must implement the FormRowHandler interface. In our case we choose to extend ValidOnlyIndividualFormRowHandler, which processes only valid form rows and allows to process them one by one, not all at once:

class PersonFormRowHandler
  extends ValidOnlyIndividualFormRowHandler {
  ...
}

The first method we have to implement is getRowKey. It is used by the form list widget to identify the row among the others. Since typically the row is just a bean we can identify it using its identifier (either a natural one or artificial, as long as its unique in this context):

...
public Object getRowKey(Object rowData) {
  return ((Person) rowData).getId();
}
...

The next method is called initAddForm and it will create a form used to add new rows to the form list:

...
public void initAddForm(FormWidget addForm) throws Exception {
  addForm.addBeanElement("name", "#First name", new TextControl(), true);
  addForm.addBeanElement("surname", "#Last name", new TextControl(),  true);
  addForm.addBeanElement("phone", "#Phone no", new TextControl(), false);

  FormListUtil.addAddButtonToAddForm("#", formList, addForm);
}
...

The bulk of the logic is just adding the fields to the add form. But we also use the FormListUtil to add a button "Add" to the form, that will take care of the actual adding a new row (or at least calling the form row handler to do that). FormListUtil contains a lot of helpful methods for manipulating form lists and more on it can be found in Section 5.3.2, “FormListUtil”. The next step would be to handle the user clicking the add button and add a new row to the model. Since we process only valid rows the method will be named addValidRow:

...
public void addValidRow(FormWidget addForm) throws Exception {
  Person person = (Person) (((BeanFormWidget)addForm).writeToBean(new Person()));
  //We want to save changes immediately
  person = lookupPersonService.addPerson(person);
  data.add(person.getId(), person);
}
...

Note that although we save the changes here immediately, form lists also support deferring this until some later point as described in Section 5.3.5, “In Memory Form List”. Now that we have added a row to the model we will also have to initialize a form for that using initFormRow method:

...
public void initFormRow(FormRow formRow, Object rowData) throws Exception {
  // Set initial status of list rows to closed - they cannot be edited before opened.
  formRow.close();

  BeanFormWidget form = (BeanFormWidget)formRow.getForm();

  form.addBeanElement("name", "#First name", new TextControl(), true);
  form.addBeanElement("surname", "#Last name", new TextControl(),  true);
  form.addBeanElement("phone", "#Phone no", new TextControl(), false);

  FormListUtil.addEditSaveButtonToRowForm("#", formList, form, getRowKey(rowData));
  FormListUtil.addDeleteButtonToRowForm("#", formList, form, getRowKey(rowData));

  form.readFromBean(rowData);
}
...

Note that most of the fields are same for add form and edit forms, so in a real setup we could easily have added a method addCommonFields(FormWidget) that would add those fields to any given form (it is actually a very common idiom to do that). Finally we have to handle the saving of row form:

...
public void saveValidRow(FormRow formRow) throws Exception {
  BeanFormWidget form = (BeanFormWidget) formRow.getForm();
  Person person = (Person) form.writeToBean(data.get(formRow.getKey()));

  lookupPersonService().save(rowData);
  data.put(person.getId(), person);
}
...

And the last one left is deletion:

...
public void deleteRow(Object key) throws Exception {
  Long id = (Long) key;
  lookupPersonService().remove(id);
  data.remove(id);
}
...

FormListUtil provides a couple of methods that help to handle form maps passed to some of the handler methods. However of main interest are the methods that add various buttons with ready logic to the add forms and row forms.

Since row form handler interface supports bulk saving/adding/deleting of row forms it is comfortable to use one of the base classes that will do some of the work for you.

Note that row handlers also have an openOrCloseRow method that may be overridden if one wants more than just inverting the row state on user action.

Often it is the case that we do not want to save the changes in the form list to the database until the user presses the "Save" button. For such a use case we provide InMemoryFormListHelper. To use the helper we first need to initialize the form list to use the helper model:

...
private BeanFormListWidget personFormList;
private InMemoryFormListHelper inMemoryHelper;

public void init() throws Exception {
  private FormListWidget personFormList;
  ...
  Map persons = lookupMyService().getPersons();

  personFormList = new BeanFormListWidget(new PersonFormRowHandler(), Person.class);
  inMemoryHelper = new InMemoryFormListHelper(
    personFormList,
    lookupPersonService().getSomePersonList());

  addWidget("personFormList", personFormList);
}
...

Now we just have to add/save/delete the row to/from the helper:

...
public void saveValidRow(FormRow editableRow) throws Exception {
  ...
  inMemoryHelper.update(editableRow.getKey(), rowData);
}

public void deleteRow(Object key) throws Exception {
  ...
  inMemoryHelper.delete(key);
}

public void addValidRow(FormWidget addForm) throws Exception {
  ...
  inMemoryHelper.add(rowData);
}
...

And when the user presses "Save" we can just process the changes:

...
protected void handleEventSave() {
  lookupPersonService.addAll(inMemoryHelper.getAdded().values());
  lookupPersonService.saveAll(inMemoryHelper.getUpdated().values());
  lookupPersonService.deleteAll(inMemoryHelper.getDeleted());
}
...

Formlist is a list of forms, an editable list. This tag specifies editable list context for its inner tags.

<?xml version="1.0" encoding="UTF-8"?>
<ui:list id="list">
    <ui:formList>
       ...
    </ui:formList>
</ui:list>

Iterating tag that gives access to each row and row form on the editable list current page. The editable row is accessible as "editableRow" variable.

<?xml version="1.0" encoding="UTF-8"?>
<ui:list id="list">
    <ui:formList>
        <ui:formListRows>
           ...
        </ui:formListRows>
    </ui:formList>
</ui:list>

Allows for adding new forms (rows) to editable list.

<?xml version="1.0" encoding="UTF-8"?>
<ui:formListAddForm>
    <ui:row>
        <ui:cell>
            <ui:textInput id="name"/>
        </ui:cell>
        
        <ui:cell>
            <ui:textInput id="surname"/>
        </ui:cell>
        
        <ui:cell>
            <ui:textInput id="phone"/>
        </ui:cell>
        
        <ui:cell>
            <ui:dateInput id="birthdate"/>
        </ui:cell>                          
    </ui:row>       
</ui:formListAddForm>