bruno 2004/04/17 10:19:59
Modified: src/documentation/xdocs/userdocs/forms
widget_booleanfield.xml widget_field.xml
widget_multivaluefield.xml widget_output.xml
widget_repeater.xml
Log:
fixes, additions, cleanup
Revision Changes Path
1.2 +15 -2
cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_booleanfield.xml
Index: widget_booleanfield.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_booleanfield.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- widget_booleanfield.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ widget_booleanfield.xml 17 Apr 2004 17:19:59 -0000 1.2
@@ -24,17 +24,30 @@
</authors>
</header>
<body>
- <s1 title="booleanfield widget">
+ <s1 title="Concept">
<p>An fd:booleanfield is a field that has a value of
true or false. Usually is rendered as a checkbox.</p>
- <p>Configuration example:</p>
+ <p>It is different from a <link href="widget_field.html">field
widget</link>
+ with a <code>boolean</code> datatype because an HTML checkbox submits
+ no request parameter if the checkbox is unchecked. If you would render
+ it instead as a listbox with true and false values, you could also
+ use a regular field widget. Since the styling preference might change
over
+ time, it is however better to use consistently the fd:booleanfield
widget.</p>
+ </s1>
+ <s1 title="Configuration">
<source><![CDATA[<fd:booleanfield id="...">
<fd:label>...</fd:label>
<fd:help>...</fd:help>
<fd:hint>...</fd:hint>
+ <fd:on-value-changed>
+ [...]
+ </fd:on-value-changed>
</fd:booleanfield>]]></source>
+
+ <p>See <link href="widget_field.html">field wiget</link> for a
description of the
+ configuration options.</p>
</s1>
</body>
</document>
1.2 +61 -29
cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_field.xml
Index: widget_field.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_field.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- widget_field.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ widget_field.xml 17 Apr 2004 17:19:59 -0000 1.2
@@ -24,45 +24,67 @@
</authors>
</header>
<body>
- <s1 title="field widget">
+ <s1 title="Concept">
<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>
- <p>[pasted the following text here from the sample, still needs some
editing to fit in]</p>
+ <figure src="images/forms_field_datatype_relation.png" alt="Diagram
showing the associations between field, datatype, convertor, selection list and
validation rules."/>
- <p>A field widget can be associated with a datatype. The function of
the datatype
- is to convert the string value entered by the user to a more specific
type
- like a number or a date (and vice versa, convert them back to strings)
- (this part is actually delegated to a seperate object: a Convertor).
- The datatype also performs the validation. (This split-up between
"widget"
- and "datatype" is specific for the field widget -- it is perfectly
possible
- to make widgets that have nothing to do with datatypes). In this way, a
- field widget contains strongly-typed data. For example, if you
associated
- a long datatype with a field widget, then you can be sure that when you
- retrieve the widget's value, you will get a Long object after the
- form was validated successfully.</p>
-
- <p>The reasoning behind the base attribute on the fd:datatype element
- is that you are actually defining a new datatype, based on the built-in
- "string" or "long" datatype, and customise it with validation rules
- (and possibly other parameters).</p>
+ <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>
- <s2 title="Defining a selection list for a field">
+ <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.
- For an example of selection lists, see the "Form1" example provided
with
- CForms. The selection-list is related with the datatype: the values
in
- the selection-list should be of the same type as the datatype.</p>
+ The selection list is related with the datatype: the values in
+ the selection list should be of the same type as the datatype.</p>
- <figure src="images/forms_field_datatype_relation.png" alt="Diagram
showing the associations between field, datatype, convertor, selection list and
validation rules."/>
+ <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:
StringField, LongField, DateField, StringSelectionList,
LongSelectionList, ...</p>
</s2>
+ </s1>
+ <s1 title="Configuration">
<p>Configuration example:</p>
<source><![CDATA[<fd:field id="..." required="true|false">
@@ -73,16 +95,22 @@
[...]
</fd:datatype>
<fd:selection-list .../>
+ <fd:validation>
+ [...]
+ </fd:validation>
<fd:on-value-changed>
- ...
+ [...]
</fd:on-value-changed>
</fd:field>]]></source>
<p>The field element takes a required <strong>id</strong> attribute.
- This id should be unique among all widgets in the same container
(usually the form).</p>
+ This id should be unique among all widgets in the same container (i.e.
inside
+ the same fd:widgets element).</p>
<p>The <strong>required</strong> attribute is optional, by default it
is false.
- It indicates whether this field is required.</p>
+ 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.</p>
<p>The <strong>fd:label</strong> element contains the label for this
widget.
This element is optional. It can contain mixed content. For
internationalised
@@ -101,14 +129,18 @@
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 here.</p>
+ configuration options are described <link href="datatypes.html">over
here</link>.</p>
<p>The <strong>fd:selection-list</strong> element is used to associate
- a selection list with this field. See Forms Datatype Reference for
more details.</p>
+ a selection list with this field. See <link
href="datatypes.html">Datatypes</link>
+ for more details.</p>
+
+ <p>The <strong>fd:validation</strong> element specifies widget
validators.
+ See <link href="validation.html">Validation</link> for more
details.</p>
<p>The <strong>fd:on-value-changed</strong> element specifies event
handlers to be executed in case the value of this field changes.
- See also Forms Event Handling. The interface to be implemented
+ See also <link href="eventhandling.html">Event Handling</link>. The
interface to be implemented
for Java event listeners is
<code>org.apache.cocoon.forms.event.ValueChangedListener</code>.
The WidgetEvent subclass is
<code>org.apache.cocoon.forms.event.ValueChangedEvent</code>.</p>
1.2 +27 -11
cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_multivaluefield.xml
Index: widget_multivaluefield.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_multivaluefield.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- widget_multivaluefield.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ widget_multivaluefield.xml 17 Apr 2004 17:19:59 -0000 1.2
@@ -24,15 +24,28 @@
</authors>
</header>
<body>
- <s1 title="multivaluefield widget">
- <p>The fd:multivaluefield is similar to the field widget but
- can take multiple values. A multivaluefield should always have
- a fd:datatype element combined with a fd:selection-list, since
- the user will have to select values from this list. The
- fd:multivaluefield could be rendered as a list of checkboxes
- or as a listbox in which the user can select multiple items.</p>
+ <s1 title="Concept">
+ <p>The fd:multivaluefield is similar to the
+ <link href="widget_field.html">field widget</link> but
+ can take multiple values. Its purpose is to handle those (HTML) form
+ controls which submit their multiple values as multiple (HTTP) request
parameters
+ with the same name. A multivaluefield should always have
+ an fd:datatype element combined with a fd:selection-list, since
+ the user will have to select values from this list.</p>
- <p>Configuration example:</p>
+ <p>The fd:multivaluefield could be rendered as a list of checkboxes
+ or as a listbox in which the user can select multiple items.
+ The CForms stylesheets also include a styling option to render
+ them as a "double list", i.e. a list of available and selected
+ values.</p>
+
+ <p>The setValue and getValue methods of the multivaluefield take
+ respectively return arrays of objects (i.e. Object[]). The type
+ of the objects in these arrays should match the datatype declared
+ for the widget.</p>
+ </s1>
+
+ <s1 title="Configuration">
<source><![CDATA[<fd:multivaluefield id="...">
<fd:label>...</fd:label>
@@ -42,11 +55,14 @@
[...]
</fd:datatype>
<fd:selection-list>
- <fd:item value="...">
- <fd:label>...</fd:label>
- </fd:item>
[...]
</fd:selection-list>
+ <fd:validation>
+ [...]
+ </fd:validation>
+ <fd:on-value-changed>
+ [...]
+ </fd:on-value-changed>
</fd:multivaluefield>]]></source>
<p>Most of the elements and attributes have the same meaning
1.2 +17 -9
cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_output.xml
Index: widget_output.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_output.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- widget_output.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ widget_output.xml 17 Apr 2004 17:19:59 -0000 1.2
@@ -24,15 +24,28 @@
</authors>
</header>
<body>
- <s1 title="output widget">
+ <s1 title="Concept">
<p>An fd:output widget is similar to a field widget, but its value
is not editable. The value of an output widget must be set
programmatically
(or through binding). An output widget does not read its value from
the request, so is most useful in the case where the form is stored
- accross requests (e.g. as part of a flowscript or flow-apple). An
+ accross requests (automatically the case when using flowscript). An
output widget does not perform any validation, it is always considered
to be valid.</p>
+ <note>It is likely that we'll add a generalized 'readonly' capability
+ to all widgets. When we do that, fd:output will become obsolete and
+ can be replaced by a 'readonly' field wiget. In the meantime you can
+ safely use fd:output since this change won't have much impact.</note>
+
+ <p><strong>Possible alternative:</strong> On each widget you can
+ also store additional information
+ (i.e. arbitrary Java objects) in attributes. See the Java API
+ of the Widget interface, methods setAttribute and getAttribute.
+ You can then retrieve these attributes using the JXTemplate
generator.</p>
+ </s1>
+
+ <s1 title="Configuration">
<source><![CDATA[<fd:output id="...">
<fd:label>...</fd:label>
<fd:help>...</fd:help>
@@ -42,13 +55,8 @@
</fd:datatype>
</fd:output>]]></source>
- <p>Note: since the fd:output widget only serves as an equivalent of
- fd:field, it has been suggested that it would be better to add a
- "read-only" capability to all widgets.</p>
-
- <p>Note: on each widget you can also store additional information
- (i.e. arbitrary Java objects) in attributes. See the Java API
- of the Widget interface, methods setAttribute and getAttribute.</p>
+ <p>See <link href="widget_field.html">field widget</link> for a
description
+ of the configuration elements.</p>
</s1>
</body>
</document>
1.2 +12 -3
cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_repeater.xml
Index: widget_repeater.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_repeater.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- widget_repeater.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ widget_repeater.xml 17 Apr 2004 17:19:59 -0000 1.2
@@ -24,16 +24,22 @@
</authors>
</header>
<body>
- <s1 title="repeater widget">
+ <s1 title="Concept">
<p>An fd:repeater widget is a widget that repeats a number of other
widgets.
It can be used to create e.g. tables, repeating subforms, etc.</p>
+ </s1>
- <p>Configuration example:</p>
-
+ <s1 title="Configuration">
<source><![CDATA[<fd:repeater id="..." initial-size="...">
+ <fd:label>...</fd:label>
+ <fd:hint>...</fd:hint>
+ <fd:help>...</fd:help>
<fd:widgets>
[...]
</fd:widgets>
+ <fd:validation>
+ [...]
+ </fd:validation>
</fd:repeater>]]></source>
<p>The <strong>fd:widgets</strong> element should contain a number of
other widgets to repeat.
@@ -43,6 +49,9 @@
<p>The optional <strong>initial-size</strong> attribute allows to
specify how much rows should
be initially present on the repeater. It mostly avoids to display a
table
with only table headers. Default value is zero.</p>
+
+ <p>For a description of the other elements, see the
+ <link href="widget_field.html">field widget</link>.</p>
<p>Note: The Forms Template Transformer has specific support for
specifying
a template to use to render each of the rows of a repeater widget. See
