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:

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.

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, add an
attribute called "dynamic" with value "true", for example:

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:

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.

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:

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.

Errors and Improvements?
If you see any errors or potential improvements in this document
please help us:
View, Edit or comment on
the latest development version (registration required).