<p>The field widget is the most common widget. It is used both for
text boxes or selection lists. It can be associated with different
datatypes such as string, long or date to ask for different types of data.</p>
<figure src="images/forms_field_datatype_relation.png" alt="Diagram showing the associations between field, datatype, convertor, selection list and validators."/>
<s2 title="Datatypes">
<p>A datatype represents a certain type of data, such as a
string, integer, decimal or date. Each datatype matches to a certain
Java class. If you associate a field widget with a datatype, its
setValue(Object) and getValue() methods will take, respectively
return objects that are instances of that Java class (or subclasses
thereof).</p>
<p>Each datatype is associated with a <strong>convertor</strong>.
The task of the convertor is to convert from string representation
to object representation, and vice versa.</p>
<p>The string to object conversion usually happens when converting
the value entered by the user to an object. This process can
fail if the user entered an incorrect string, for example
<code>abc</code> when a number is required. In this case
an appropriate validation error will be set on the widget.
String to object conversion also happens when parsing data
in selection lists (if the selection list is retrieved as XML)
and can also be used as part of the <link href="binding.html">binding</link>.</p>
<p>The object to string conversion happens when the state
of the widget is spit out as XML, this is mostly when injecting
the widget XML in the publishing pipeline.</p>
<p>By having a field widget associated with a datatype, you can be sure
that, after successful validation of the widget, retrieving the value
of the widget will give you an object of the correct type.</p>
<p>The available datatypes and their respective convertors are
documented in a <link href="datatypes.html">separate document</link>.</p>
</s2>
<s2 title="Selection lists">
<p>A field widget can furthermore be associated with a selection list.
This makes that the field widget could be rendered either as a textbox
or a list, depending on whether its datatype has a selection list.
The selection list is related with the datatype: the values in
the selection list should be of the same type as the datatype.</p>
<p>Selection list data can be specified directly in the form definition
(for short, unchanging lists), retrieved from external sources (i.e.
a Cocoon pipeline), or pulled from an oject structure. Full details on
selection lists are also in a <link href="datatypes.html">separate document</link>.</p>
</s2>
<s2 title="Conclusion">
<p>If we wouldn't make these datatype and selection list associations,
we would need to create specific widgets for each possible combination:
