Field widget

Concept

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.

forms_field_datatype_relation

Datatypes

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).

Each datatype is associated with a convertor. The task of the convertor is to convert from string representation to object representation, and vice versa.

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 abc 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 binding.

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.

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.

The available datatypes and their respective convertors are documented in a separate document.

Selection lists

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.

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 separate document.

Conclusion

If we wouldn't make these datatype and selection list associations, we would need to create specific widgets for each possible combination: StringField, LongField, DateField, StringSelectionList, LongSelectionList, ...

Definition

Configuration example:

<fd:field id="..." required="true|false" state="..."
          whitespace="trim|trim-start|trim-end|preserve">
  <fd:label>...</fd:label>
  <fd:hint>...</fd:hint>
  <fd:help>...</fd:help>
  <fd:datatype base="...">
     [...]
  </fd:datatype>
  <fd:initial-value locale="...">...</fd:initial-value>
  <fd:selection-list .../>
  <fd:suggestion-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:field>

The field element takes a required id attribute. This id should be unique among all widgets in the same container (i.e. inside the same fd:widgets element).

The required attribute is optional, by default it is false. It indicates whether this field is required. This is a static property of the widget. If you want the field to be "conditionally required", then set this to false and use custom validation logic to check the requiredness of the field.

The state attribute is optional. See Widget States for its purpose.

The whitespace attribute is optional. It controls how leading and trailing whitespace characters are handled when the widget parses the value submitted by the user. Accepted values are: "trim" (removes both leading and trailing whitespace), "trim-start" (removes leading whitespace only), "trim-end" (removes trailing whitespace only), and "preserve" (leaves both leading and trailing whitespace intact). If the whitespace attribute is not present, it defaults to "trim".

The fd:label element contains the label for this widget. This element is optional. It can contain mixed content. For internationalised labels, use i18n-tags in combination with Cocoon's I18nTransformer.

The fd:hint element contains a hint for the form control of this widget. This element is optional. It can contain a hint about the input control. For internationalised labels, use i18n-tags in combination with Cocoon's I18nTransformer.

The fd:help element contains more help for the form control of this widget. This element is optional. It can contain text help about the input control. For internationalised labels, use i18n-tags in combination with Cocoon's I18nTransformer.

The fd:datatype element indicates the datatype for this field. This element is required. The base attribute specifies on which built-in type this datatype should be based. The contents of the fd:datatype element can contain further configuration information for the datatype. The possible datatypes and their configuration options are described over here.

The fd:initial-value element specifies an initial value for the field. The specified string value is converted using the datatype's convertor. You can optionally define the locale to be used for this.

The fd:selection-list element is used to associate a selection list with this field. See Datatypes for more details.

The fd:suggestion-list element is similar to the fd:selection-list element but serves for Ajax-based autocompletion. (Very new at the time of this writing -- sep/oct 2005)

The fd:validation element specifies widget validators. See Validation for more details.

The fd:on-value-changed element specifies event handlers to be executed in case the value of this field changes. See also Event Handling. The interface to be implemented for Java event listeners is org.apache.cocoon.forms.event.ValueChangedListener. The WidgetEvent subclass is org.apache.cocoon.forms.event.ValueChangedEvent.

The fd:on-create element specifies event handlers to be executed upon creation of the widget instance. The interface to be implemented for Java event listeners is org.apache.cocoon.forms.event.CreateListener.

The fd:attributes element specifies arbitrary name/value pairs to be associated with the widget. These attributes have no special meaning to CForms itself, but can be retrieved via the API.

Note: Note: Events used in <fd:on-value-changed> require that the form instance is stored serverside (because otherwise CForms doesn't know what the previous values of the fields were). This is automatically the case when you use flowscript. If you don't use flowscript you could store the form instance in e.g. the session.

Template

A field widget is inserted in a template using the ft:widget tag:

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

Styling (default HTML XSL)

If the field widget does not have a selection list, it will be rendered as simple input box. If the field widget does have a selection list, it will by default be rendered as a dropdown list. If the datatype of the field is date, a date-picker icon will be put next to the field.

Note: The following applies only if you use the default (i.e. provided) XSL stylesheets. It is entirely up to you if you want to redefine these XSL sheets with different styling tags. However, since the provided XSL sheets are very generic and flexible, think twice before you start redoing the work.

To render the input field as a textarea:

<ft:widget id="...">
  <fi:styling type="textarea"/>
</ft:widget>

To render the input field as a HTMLArea:

<ft:widget id="...">
  <fi:styling type="htmlarea"/>
</ft:widget>

To render the selection lists as a listbox:

<ft:widget id="...">
  <fi:styling list-type="listbox" list-size="5"/>
</ft:widget>

To render the selection list as radio buttons:

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

To render the selection list as horizontal radio buttons:

<ft:widget id="...">
  <fi:styling list-type="radio" list-orientation="horizontal"/>
</ft:widget>

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).

Cocoon Forms 1.0