A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/753.html
Document ID: 753
Branch: main
Language: default
Name: Selection lists
Document Type: Cocoon Document
Created: 10/23/05 1:48:18 PM
Creator (owner): Bruno Dumon
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 5673 bytes
Content:
<html>
<body>
<p>This section explains selection lists and their available implementations.
Selection lists can be used with the <a href="daisy:481">field</a> or
<a href="daisy:490">multivaluefield</a> 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.</p>
<h1>Default selection list implementation</h1>
<p>The selection list can be defined inline or read from an external source.
Example of inline declaration:</p>
<pre><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><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><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><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>
<h1>flow-jxpath selection list implementation</h1>
<p>See the javadoc of the
<a
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>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><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>importClass (Packages.org.apache.cocoon.forms.util.I18nMessage);
...
mylist[0] = {value: "x", label: new I18nMessage("myI18nKey") };</pre>
<h1>enum selection list implementation</h1>
<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><fd:selection-list type="enum" class="com.example.Sex"/></pre>
<p>outputs:</p>
<pre><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>
</body>
</html>
Collections
===========
The document belongs to the following collections: documentation
