You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by br...@apache.org on 2004/04/17 19:19:59 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/forms widget_booleanfield.xml widget_field.xml widget_multivaluefield.xml widget_output.xml widget_repeater.xml
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