| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Cocoon Forms: Datatypes</title> |
| <link href="http://purl.org/DC/elements/1.0/" rel="schema.DC"> |
| <meta content="The Apache Cocoon Team" name="DC.Creator"> |
| </head> |
| <body> |
| |
| <h1>Context</h1> |
| |
| <p>Datatypes are used by certain widgets, more specifically the |
| <a href="widget_field.html">field</a> and |
| <a href="widget_multivaluefield.html">multivaluefield</a> |
| widgets, to allow them to edit different types of data |
| (e.g. strings, numbers, dates). For a general introduction |
| of the relationship between the widget and the datatype, |
| see the documentation of the <a href="widget_field.html">field</a> |
| widget.</p> |
| |
| |
| |
| <h1>General information</h1> |
| |
| <p>In its most basic form a datatype is declared as follows:</p> |
| |
| |
| <pre class="code"><fd:datatype base="..."></pre> |
| |
| |
| <p>The <strong>base</strong> attribute refers to one of the built-in |
| datatypes such as string or long.</p> |
| |
| |
| <h2>Convertors</h2> |
| <p>A datatype 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 fd:convertor element. Here's an example for dates:</p> |
| <pre class="code"><fd:datatype base="date"> |
| <fd:convertor type="formatting"> |
| <fd:patterns> |
| <fd:pattern>dd/MM/yyyy</fd:pattern> |
| </fd:patterns> |
| </fd:convertor> |
| </fd:datatype></pre> |
| <p>The <strong>type</strong> attribute on the fd:convertor element |
| is optional, if not specified the default one will be used (configured |
| in the cocoon.xconf). Any further content of the fd:convertor element |
| is specific to the convertor implementation and will be documented |
| in a seperate section.</p> |
| |
| |
| <h2>Selection lists (default implementation)</h2> |
| <p>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:</p> |
| <pre class="code"><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></pre> |
| <p>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.</p> |
| <p>To set a default selection, just set the value of the widget |
| containing the selection list.</p> |
| <p>Example of getting a selection list from an external source:</p> |
| <pre class="code"><fd:datatype base="string"/> |
| <fd:selection-list src="cocoon:/mychoices.xml"/></pre> |
| <p>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.</p> |
| <p>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:</p> |
| <pre class="code"><fd:datatype base="string"/> |
| <fd:selection-list src="cocoon:/mychoices.xml" dynamic="true"/></pre> |
| <p>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:</p> |
| <pre class="code"><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></pre> |
| <p>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.</p> |
| <p>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 <strong>type</strong> attribute |
| on the fd:selection-list element. The sections below describe the |
| alternative implementations currently available.</p> |
| |
| |
| <h2>Selection lists: flow-jxpath implementation</h2> |
| <p>See the javadoc of the <a class="external" href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/src/blocks/forms/java/org/apache/cocoon/forms/datatype/FlowJXPathSelectionListBuilder.java?rev=HEAD">FlowJXPathSelectionListBuilder</a> class for now.</p> |
| <p>Example:</p> |
| <p>In flowscript:</p> |
| <pre class="code">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);</pre> |
| <p>and the corresponding selection list definition:</p> |
| <pre class="code"><fd:selection-list type="flow-jxpath" list-path="cityList" value-path="value" label-path="label" /></pre> |
| <p>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:</p> |
| <pre class="code">importClass (Packages.org.apache.cocoon.forms.util.I18nMessage); |
| ... |
| mylist[0] = {value: "x", label: new I18nMessage("myI18nKey") };</pre> |
| |
| |
| <h2>Selection lists: enum implementation</h2> |
| <p>This type of selection list outputs a list of items corresponding |
| to the possible instances of an enumerated type (see below).</p> |
| <p>Example:</p> |
| <pre class="code"><fd:selection-list type="enum" class="com.example.Sex"/></pre> |
| <p>outputs:</p> |
| <pre class="code"><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></pre> |
| <p>If you don't want an initial null value, add a <strong>nullable="false"</strong> |
| attribute to the <strong>fd:selection-list</strong> element. This applies only to |
| <strong>enum</strong> type selection lists.</p> |
| |
| |
| |
| <h1>Available datatypes</h1> |
| |
| <table> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">CForms datatype</th> |
| <th colspan="1" rowspan="1">Java class</th> |
| <th colspan="1" rowspan="1">Convertors</th> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">string</td> |
| <td colspan="1" rowspan="1">java.lang.String</td> |
| <td colspan="1" rowspan="1">Strings obviously don't support any convertors, since there's no purpose in converting a string to a string.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">decimal</td> |
| <td colspan="1" rowspan="1">java.math.BigDecimal</td> |
| <td colspan="1" rowspan="1">formatting (decimal), plain</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">integer</td> |
| <td colspan="1" rowspan="1">java.lang.Integer</td> |
| <td colspan="1" rowspan="1">similar as decimal datatype</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">long</td> |
| <td colspan="1" rowspan="1">java.lang.Long</td> |
| <td colspan="1" rowspan="1">similar as decimal datatype</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">double</td> |
| <td colspan="1" rowspan="1">java.lang.Double</td> |
| <td colspan="1" rowspan="1">similar as decimal datatype</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">date</td> |
| <td colspan="1" rowspan="1">java.util.Date</td> |
| <td colspan="1" rowspan="1">formatting (date), millis</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">enum</td> |
| <td colspan="1" rowspan="1">Enumerated type</td> |
| <td colspan="1" rowspan="1">enum</td> |
| |
| </tr> |
| |
| </table> |
| |
| |
| <h2>Enumerated datatype</h2> |
| <p>The <strong>enum</strong> datatype is meant to be used with types |
| implementing Joshua Bloch's <a class="external" href="http://developer.java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums">typesafe enum pattern</a>. |
| The following is a possible implementation:</p> |
| <pre class="code">package com.example; |
| |
| public class Sex { |
| |
| public static final Sex MALE = new Sex("M"); |
| public static final Sex FEMALE = new Sex("F"); |
| private String code; |
| |
| private Sex(String code) { this.code = code; } |
| }</pre> |
| <p>The following snippet shows the usage of this type:</p> |
| <pre class="code"><fd:field id="sex"> |
| <fd:label>Sex</fd:label> |
| <fd:datatype base="enum"> |
| <fd:convertor type="enum"> |
| <fd:enum>com.example.Sex</fd:enum> |
| </fd:convertor> |
| </fd:datatype> |
| <fd:selection-list type="enum" class="com.example.Sex"/> |
| </fd:field></pre> |
| <p>If your enumerated type does not provide a <span class="codefrag">toString()</span> method, |
| the enum convertor will use the fully qualified class name, followed by the |
| name of the <span class="codefrag">public static final</span> field referring to each instance, |
| i.e. "<span class="codefrag">com.example.Sex.MALE</span>", "<span class="codefrag">com.example.Sex.FEMALE</span>" and so on.</p> |
| <p>If you provide a <span class="codefrag">toString()</span> method which returns something |
| different, you should also provide a <span class="codefrag">fromString(String, Locale)</span> |
| method to convert those strings back to instances.</p> |
| <p>The enum datatype is typically used together with the <strong>enum</strong> selection list type.</p> |
| |
| |
| |
| <h1>Available convertors</h1> |
| |
| <h2>formatting (decimal)</h2> |
| <p>This convertor uses the <span class="codefrag">java.text.DecimalFormat</span> |
| class (or <span class="codefrag">com.ibm.icu.text.DecimalFormat</span> class if it is |
| present in the classpath). This means it can perform locale-dependent, |
| pattern-based formatting of numbers.</p> |
| <p>Configuration pseudo-schema:</p> |
| <pre class="code"><fd:convertor type="formatting" variant="integer|number|currency|percent" ? > |
| <fd:patterns> |
| <fd:pattern>....</fd:pattern> ? |
| <fd:pattern locale="lang-COUNTRY">....</fd:pattern> * |
| </fd:patterns> ? |
| </fd:convertor></pre> |
| <p>The variant attribute and patterns element are optional. By |
| default, the "number" variant is used (or for longs: the "integer" variant).</p> |
| <p>You can supply either a locale-independent formatting pattern or |
| locale-dependent formatting patterns. See the |
| <a class="external" href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/DecimalFormat.html">javadoc of the DecimalFormat class</a> |
| for the supported pattern syntax. CForms will always use the pattern |
| that is most specific for the current locale.</p> |
| |
| |
| <h2>plain</h2> |
| <p>This convertor is not locale-dependent. It shows the full |
| precision of the number and uses dot as the decimal separator.</p> |
| |
| |
| <h2>date convertors</h2> |
| <p>The date datatype can be used both for dates as times. The date datatype supports the following convertors:</p> |
| <h3>formatting (date)</h3> |
| <p>This convertor uses the <span class="codefrag">java.text.SimpleDateFormat</span> class |
| (or <span class="codefrag">com.ibm.icu.text.SimpleDateFormat</span> class if it is present |
| in the classpath). This means it can perform locale-dependent, pattern-based |
| formatting of dates.</p> |
| <p>Configuration pseudo-schema:</p> |
| <pre class="code"><fd:convertor type="formatting" variant="date|time|datetime" ? style="short|medium|long|full" ?> |
| <fd:patterns> |
| <fd:pattern>....</fd:pattern> ? |
| <fd:pattern locale="lang-COUNTRY">....</fd:pattern> * |
| </fd:patterns> ? |
| </fd:convertor></pre> |
| <p>Usually you will use either the variant and style attributes or the pattern(s).</p> |
| <p>For example, the following convertor configuration:</p> |
| <pre class="code"><fd:convertor type="formatting" variant="date" style="short"></pre> |
| <p>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.</p> |
| <p>Here's an example of using a formatting pattern:</p> |
| <pre class="code"><fd:convertor type="formatting"> |
| <fd:patterns> |
| <fd:pattern>dd/MM/yyyy</fd:pattern> |
| </fd:patterns> |
| </fd:convertor></pre> |
| <p>Using the same date, this will now give "15/07/2003".</p> |
| <p>It is also possible to use different patterns for different |
| locales by using multiple fd:pattern elements with "locale" attributes, for example:</p> |
| <pre class="code"><fd:convertor type="formatting"> |
| <fd:patterns> |
| <fd:pattern>MM/dd/yyyy</fd:pattern> |
| <fd:pattern locale="nl-BE">dd/MM/yyyy</fd:pattern> |
| <fd:pattern locale="fr">dd-MM-yyyy</fd:pattern> |
| </fd:patterns> |
| </fd:convertor></pre> |
| <p>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).</p> |
| <h3>millis</h3> |
| <p>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.</p> |
| |
| |
| </body> |
| </html> |
