In its most basic form a datatype is declared as follows:
The base attribute refers to one of the built-in datatypes such as string or long.
Update: Validaton rules have been moved out of the datatype, see the WoodyWidgetReference for how to set them directly on the field widget.
A datatype also needs a convertor. The purpose of a convertor is to convert between string and object representations of values. There is always a default convertor, but you change or configure that using the wd:convertor element. Here's an example for dates:
The type attribute on the wd:convertor element is optional, if not specified the default one will be used (configured in the cocoon.xconf). Any further content of the wd:convertor element is specific to the convertor implementation and will be documented in a seperate section.
Selection lists (default implementation)
Widgets that have a datatype can also have a selection list. Since selection lists are associated with datatypes, we discuss them here. 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 wd:label element). If no label is specified, the value is used as label. The wd: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:
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 wd: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 Woody 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, Woody 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 wd:convertor element, it should always be the first child element of the wd: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 wd:selection-list element. There is currently one alternative implementation: flow-jxpath.
Selection lists: flow-jxpath implementation
See the javadoc of the FlowJXPathSelectionListBuilder class for now.
and the corresponding selection list definition:
Selection lists: enum implementation
This type of selection list outputs a list of items corresponding to the possible instances of an enumerated type (see below).
If you don't want an initial null value, add a nullable="false" attribute to the wd:selection-list element. This applies only to enum type selection lists.
Strings obviously don't support any convertors, since there's no purpose in converting a string to a string.
formatting (decimal), plain
similar as decimal datatype
similar as decimal datatype
formatting (date), millis
The enum datatype is meant to be used with types implementing Joshua Bloch's typesafe enum pattern. The following is a possible implementation:
The following snippet shows the usage of this type:
If your enumerated type does not provide a
toString() method, the enum convertor will use the fully qualified class name, followed by the name of the
public static final field referring to each instance, i.e.
"com.example.Sex.FEMALE" and so on.
If you provide a
toString() method which returns something different, you should also provide a
fromString(String, Locale) method to convert those strings back to instances.
The enum datatype is typically used together with the enum selection list type.
This convertor uses the
java.text.DecimalFormat class (or
com.ibm.icu.text.DecimalFormat class if it is present in the classpath). This means it can perform locale-dependent, pattern-based formatting of numbers.
The variant attribute and patterns element are optional. By default, the "number" variant is used (or for longs: the "integer" variant).
You can supply either a locale-independent formatting pattern or locale-dependent formatting patterns. See the javadoc of the DecimalFormat class for the supported pattern syntax. Woody will always use the pattern that is most specific for the current locale.
This convertor is not locale-dependent. It shows the full precision of the number and uses dot as the decimal separator.
The date datatype can be used both for dates as times. The date datatype supports the following convertors:
This convertor uses the
java.text.SimpleDateFormat class (or
com.ibm.icu.text.SimpleDateFormat class if it is present in the classpath). This means it can perform locale-dependent, pattern-based formatting of dates.
Usually you will use either the variant and style attributes or the pattern(s).
For example, the following convertor configuration:
Will give the following for July 15, 2003: 7/15/03. Using style medium it gives "Jul 15, 2003", style long gives "July 15, 2003", and style full gives "Tuesday, July 15, 2003". These result are locale-dependent of course.
Here's an example of using a formatting pattern:
Using the same date, this will now give "15/07/2003".
It is also possible to use different patterns for different locales by using multiple wd:pattern elements with "locale" attributes, for example:
In this case, if the locale is "nl-BE", the second pattern will be used; if the locale is "en", the first pattern will be used; and if the locale is "fr-BE" the third pattern will be used (because when fr-BE is not found, it will first search for "fr" before using the locale-indepent pattern).
The millis convertor for dates uses the number of milliseconds since January 1, 1970, 00:00:00 GMT as string representation. This will likely not be used to present dates to the user, but may be useful in selection lists retrieved from external sources.