Selection lists

This section explains selection lists and their available implementations. Selection lists can be used with the field or multivaluefield widgets. Selection lists are closely related to the datatype of the widget, since the items in the selection list should of course match the datatype of the widget.

Default selection list implementation

The selection list can be defined inline or read from an external source. Example of inline declaration:

<fd:datatype base="long"/>
<fd:selection-list>
  <fd:item value="1"/>
  <fd:item value="2"/>
  <fd:item value="3">
    <fd:label>three</fd:label>
  </fd:item>
  <fd:item value="4"/>
  <fd:item value="5"/>
</fd:selection-list>

Each item in the selection-list can have a value (specified in the value attribute) and optionally a label (specified in the fd:label element). If no label is specified, the value is used as label. The fd:label element can contain mixed content.

To set a default selection, just set the value of the widget containing the selection list.

Example of getting a selection list from an external source:

<fd:datatype base="string"/>
<fd:selection-list src="cocoon:/mychoices.xml"/>

All Cocoon-supported protocols can be used. The format of the XML produced by the source should be the same as in case of inline specification of the selection list, thus the root element should be a fd:selection-list element.

By default, the selection list will be retrieved form the source once, and then become part of the form definition, just like when you would have defined it inline. This has the consequence that if the XML produced by the source changes, you won't see the selection list changed. If you'd like CForms to retrieve the content of the selection list each time it needs it or one per request, add an attribute called "cache" with value "none" or "request" respectively, for example:

<fd:datatype base="string"/>
<fd:selection-list src="cocoon:/mychoices.xml" cache="none"/>

If the datatype is different from string, CForms will need to convert the string values that appear in the selection list to their object equivalent. This conversion is normally done using the same convertor as the datatype in which the selection list appears, but you can also specify a different one. Here's an example for a date selection list:

<fd:datatype base="date"/>
<fd:selection-list>
  <fd:convertor type="formatting">
    <fd:patterns>
      <fd:pattern>yyyyMMdd</fd:pattern>
    </fd:patterns>
  </fd:convertor>
  <fd:item value="13020711"/>
  <fd:item value="19120623"/>
  <fd:item value="19690721"/>
  <fd:item value="19700506"/>
  <fd:item value="19781014"/>
  <fd:item value="20010911"/>
</fd:selection-list>

If there is a fd:convertor element, it should always be the first child element of the fd:selection-list element. This works of course also for selection lists retrieved from external sources.

Selection list implementations are pluggable. Everything said until now applies to the default selection list implementation. An alternative implementation can be specified by using a type attribute on the fd:selection-list element. The sections below describe the alternative implementations currently available.

flow-jxpath selection list implementation

See the javadoc of the FlowJXPathSelectionListBuilder class for now.

Example:

In flowscript:

var data = new Object();

data.cityList = new Array(2);
data.cityList[0] = {value:"AL", label:"Alabama"};
data.cityList[1] = {value:"AK", label:"Alaska"};

form.showForm("flow/myform.form", data);

and the corresponding selection list definition:

<fd:selection-list type="flow-jxpath" list-path="cityList"
                   value-path="value" label-path="label" />

Hint: the label can be any kind of object, its toString() method will be called to get the string to be displayed. In case the object supplied as label implements the XMLizable interface, its toSAX method will be called instead. One practical application of this is using i18n labels:

importClass (Packages.org.apache.cocoon.forms.util.I18nMessage);
...
mylist[0] = {value: "x", label: new I18nMessage("myI18nKey") };

enum selection list implementation

This type of selection list outputs a list of items corresponding to the possible instances of an enumerated type (see below).

Example:

<fd:selection-list type="enum" class="com.example.Sex"/>

outputs:

<fi:selection-list>
  <fi:item value=""/>
  <fi:item value="com.example.Sex.MALE">
    <fi:label>
      <i18n:text>com.example.Sex.MALE</i18n:text>
    </fi:label>
  </fi:item>
  <fi:item value="com.example.Sex.FEMALE">
    <fi:label>
      <i18n:text>com.example.Sex.FEMALE</i18n:text>
    </fi:label>
  </fi:item>
</fi:selection-list>

If you don't want an initial null value, add a nullable="false" attribute to the fd:selection-list element. You can specify an i18n key to use as a label for the null element using the null-text="i18.key.here" attribute. This applies only to enum type selection lists.

Note : since the enum pattern is based on Class.getDeclaredFields() method, it's not always granted that the enum selection list items will be in the same order the fields are declared in the enumeration class. This is reported to happen expecially on IBM JRE. A good solution to this problem is to use the apache commons Enum as a super class of your enumeration classes. Due to the way this enumeration pattern is implemented, it's possible to grant the element orders in a portable way.