MultiValueField widget

Concept

The fd:multivaluefield is similar to the field widget but can take multiple values. Its purpose is to handle those (HTML) form controls which submit their multiple values as multiple (HTTP) request parameters with the same name.

Note: Before Cocoon 2.1.8, multivaluefields required a selection list, since no input method was available for multivaluefields without a selection list. Since Cocoon 2.1.8, this requirement has been dropped and a free-entry multivaluefield styling is available.

The multivaluefield can be rendered in various ways, as described in the styling section.

The setValue and getValue methods of the multivaluefield take, respectively return, arrays of objects (i.e. Object[]). The type of the objects in these arrays should match the datatype declared for the widget.

Definition

<fd:multivaluefield id="..." state="...">
  <fd:label>...</fd:label>
  <fd:help>...</fd:help>
  <fd:hint>...</fd:hint>
  <fd:datatype base="...">
    [...]
  </fd:datatype>
  <fd:selection-list>
    [...]
  </fd:selection-list>
  <fd:validation>
    [...]
  </fd:validation>
  <fd:on-value-changed>
     [...]
  </fd:on-value-changed>
  <fd:on-create>
    [..]
  </fd:on-create>
  <fd:attributes>
    <fd:attribute name="..." value="..."/>
  </fd:attributes>
</fd:multivaluefield>

Most of the elements and attributes have the same meaning as for the field widget.

Note: A multivaluefield cannot have a required attribute, instead you should use the value-count validator to check the number of values the user has selected.

Template

A multivaluefield is inserted into a template using the normal ft:widget tag:

<ft:widget id="..."/>

Styling (default HTML XSL)

If the multivaluefield has a selection list, it will by default be rendered as a list in which multiple items can be selected. Alternative, more user-friendly styling options are also possible.

Rendering the multivaluefield as two listboxes between which the items can be moved:

<ft:widget id="...">
  <fi:styling list-type="double-listbox">
    <fi:available-label>Available</fi:available-label>
    <fi:selected-label>Selected</fi:selected-label>
  </fi:styling>
</ft:widget>

Rendering the multivaluefield as checkboxes:

<ft:widget id="...">
  <fi:styling list-type="checkbox"/>
</ft:widget>

If the multivaluefield does not have a selection list, it will be styled as an input box with a listbox below it. Items can be entered in the input box, when pressing enter they are added to the listbox. Items can be deleted by selecting them and pressing the delete button. The items can be rearranged by selecting them and using ctrl+up/down arrow. An existing item can be edited by selecting it, editing the value and pressing ctrl+enter.

API notes

As mentioned above, the value of multivaluefield widget is a Java array. So when using the API from javascript, you also need to create a Java array. For example, if the datatype of the field is "long", you could create an array as follows:

var values = java.lang.reflect.Array.newInstance(java.lang.Long.TYPE, 3);
values[0] = 1;
values[1] = 2;
values[2] = 3;
multivaluefield.setValue(values);