bruno 2004/04/17 11:29:28
Modified: src/documentation/xdocs/userdocs/forms datatypes.xml
index.xml sample.xml validation.xml
widget_field.xml widget_multivaluefield.xml
Log:
Updates to reflect the fact that datatype validation rules have now become
widget validators.
Revision Changes Path
1.3 +2 -17
cocoon-2.1/src/documentation/xdocs/userdocs/forms/datatypes.xml
Index: datatypes.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/datatypes.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- datatypes.xml 17 Apr 2004 16:25:28 -0000 1.2
+++ datatypes.xml 17 Apr 2004 18:29:28 -0000 1.3
@@ -18,7 +18,7 @@
<document>
<header>
- <title>Apache Cocoon Forms: Datatypes</title>
+ <title>Cocoon Forms: Datatypes</title>
<authors>
<person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
</authors>
@@ -43,23 +43,8 @@
<p>The <strong>base</strong> attribute refers to one of the built-in
datatypes such as string or long.</p>
- <s2 title="Validation rules">
- <p>A datatype can have a number of validation rules, for example:</p>
-
- <source><![CDATA[<fd:datatype base="string">
- <fd:validation>
- <fd:length exact='4'/>
- </fd:validation>
-</fd:datatype>]]></source>
-
- <p>The <strong>fd:validation</strong> element contains a number of
- child elements, each child element signifies a validation rule.
- The supported validation rules are documented in the
- <link href="validation.html">Validation Rule Reference</link>.</p>
- </s2>
-
<s2 title="Convertors">
- <p>A datatype also needs a convertor. The purpose of a convertor
+ <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>
1.2 +1 -1
cocoon-2.1/src/documentation/xdocs/userdocs/forms/index.xml
Index: index.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ index.xml 17 Apr 2004 18:29:28 -0000 1.2
@@ -113,7 +113,7 @@
their value from the request. Some might generate events, which will
be handled by event handlers. Validation of the widget tree is also
triggered, whereby all widgets will validate themselves based on
- validation rules described in the form definition. The controller
+ widget validators described in the form definition. The controller
can afterwards perform application-specific validation logic.</li>
<li>If there were validation errors, the form will be redisplayed.
Otherwise the controller will decide what's the next step, for
1.2 +22 -27
cocoon-2.1/src/documentation/xdocs/userdocs/forms/sample.xml
Index: sample.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/sample.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- sample.xml 14 Apr 2004 19:04:34 -0000 1.1
+++ sample.xml 17 Apr 2004 18:29:28 -0000 1.2
@@ -50,49 +50,44 @@
<fd:widgets>
<fd:field id="name" required="true">
<fd:label>Name:</fd:label>
- <fd:datatype base="string">
- <fd:validation>
- <fd:length min="2"/>
- </fd:validation>
- </fd:datatype>
+ <fd:datatype base="string"/>
+ <fd:validation>
+ <fd:length min="2"/>
+ </fd:validation>
</fd:field>
<fd:field id="email" required="true">
<fd:label>Email address:</fd:label>
- <fd:datatype base="string">
- <fd:validation>
- <fd:email/>
- </fd:validation>
- </fd:datatype>
+ <fd:datatype base="string"/>
+ <fd:validation>
+ <fd:email/>
+ </fd:validation>
</fd:field>
<fd:field id="age">
<fd:label>Your age:</fd:label>
- <fd:datatype base="long">
- <fd:validation>
- <fd:range min="0" max="150"/>
- </fd:validation>
- </fd:datatype>
+ <fd:datatype base="long"/>
+ <fd:validation>
+ <fd:range min="0" max="150"/>
+ </fd:validation>
</fd:field>
<fd:field id="password" required="true">
<fd:label>Password:</fd:label>
- <fd:datatype base="string">
- <fd:validation>
- <fd:length min="5" max="20"/>
- </fd:validation>
- </fd:datatype>
+ <fd:datatype base="string"/>
+ <fd:validation>
+ <fd:length min="5" max="20"/>
+ </fd:validation>
</fd:field>
<fd:field id="confirmPassword" required="true">
<fd:label>Re-enter password:</fd:label>
- <fd:datatype base="string">
- <fd:validation>
- <fd:assert test="password = confirmPassword">
- <fd:failmessage>The two passwords are not equal.</fd:failmessage>
- </fd:assert>
- </fd:validation>
- </fd:datatype>
+ <fd:datatype base="string"/>
+ <fd:validation>
+ <fd:assert test="password = confirmPassword">
+ <fd:failmessage>The two passwords are not equal.</fd:failmessage>
+ </fd:assert>
+ </fd:validation>
</fd:field>
<fd:booleanfield id="spam">
1.2 +100 -59
cocoon-2.1/src/documentation/xdocs/userdocs/forms/validation.xml
Index: validation.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/validation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- validation.xml 17 Apr 2004 16:25:28 -0000 1.1
+++ validation.xml 17 Apr 2004 18:29:28 -0000 1.2
@@ -18,19 +18,46 @@
<document>
<header>
- <title>Apache Cocoon Forms: Validation Rules</title>
+ <title>Cocoon Forms: Validation</title>
<authors>
<person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
</authors>
</header>
<body>
- <s1 title="General">
- <p>For each validation rule, the failmessage (i.e. the message
displayed
- to the user in case the validation failed) can be overridden by
specifying
- a child <strong>fd:failmessage</strong> element inside the validation
rule element. The
- failmessage can contain mixed content. Example:</p>
+ <s1 title="Concept">
+ <p>For each widget you can define a number of widget validators. A
+ widget validator can perform some checks on the widget and if these
+ fail, set a validation error on the widget.</p>
+
+ <p>Note that technically, it is not required that really each widget
+ supports widget validators, but all the ones supplied with CForms
do.</p>
+
+ <p>Implementation-wise, a widget validator is an object implementing
+ the <code>WidgetValidator</code> interface. [insert javadoc link
+ once those are published]</p>
+
+ <p>Validation errors can only be set on widgets implementing
+ the interface <code>ValidationErrorAware</code>, which currently is not
+ implemented by all widgets. For example, a repeater widget does not
+ implement ValidationErrorAware. However, a validator attached to
+ a repeater could perform inter-row checks on the fields in the
+ different rows of the repeater, and set validation errors on these
+ fields (instead of on the repeater itself).</p>
+
+ <p>CForms supplies a number of widget validators, mostly for performing
+ checks on the value of field widgets. Additionally you can write your
+ own ones in Java or in Javascript.</p>
+ </s1>
+
+ <s1 title="Reference">
+ <s2 title="General remarks">
+ <p>For most widget validators, the failmessage (i.e. the message
displayed
+ to the user in case the validation failed) can be overridden by
specifying
+ a child <strong>fd:failmessage</strong> element inside the validator
element. The
+ failmessage can contain mixed content. Example:</p>
- <source><![CDATA[<fd:datatype base="string">
+ <source><![CDATA[<fd:field id="yourmail">
+ <fd:datatype base="string"/>
<fd:validation>
<fd:email>
<fd:failmessage>Not a valid email address!</fd:failmessage>
@@ -38,52 +65,54 @@
</fd:validation>
</fd:datatype>]]></source>
- <p>To provide locale-dependent messages, use i18n tags in
- combination with the I18nTransformer.</p>
+ <p>To provide locale-dependent messages, use i18n tags in
+ combination with the I18nTransformer.</p>
- <p>Often the values that validation rules will check are specified as
- expressions. CForms uses for this the <link
href="http://xreporter.cocoondev.org/en/expressions.html";>xReporter expression
interpreter</link>.</p>
- </s1>
+ <p>Often the values that validators will check are specified as
+ expressions. CForms uses for this the <link
href="http://xreporter.cocoondev.org/en/expressions.html";>xReporter expression
interpreter</link>.</p>
- <s1 title="Summary">
- <table>
- <tr>
- <th>Validator</th>
- <th>Allowed datatypes</th>
- </tr>
- <tr>
- <td>assert</td>
- <td>all datatypes</td>
- </tr>
- <tr>
- <td>email</td>
- <td>string</td>
- </tr>
- <tr>
- <td>length</td>
- <td>string</td>
- </tr>
- <tr>
- <td>mod10</td>
- <td>string</td>
- </tr>
- <tr>
- <td>range</td>
- <td>integer, long, decimal</td>
- </tr>
- <tr>
- <td>regexp</td>
- <td>string</td>
- </tr>
- <tr>
- <td>value-count</td>
- <td>all datatypes as part of multivaluefield</td>
- </tr>
- </table>
- </s1>
+ <p>Note that you cannot use each validator with each widget. Most
validators
+ only work with certain types of widgets, in case of field widgets
+ often expecting a specific datatype. The below table shows the
supported combinations
+ for the default validators.</p>
+
+ <table>
+ <tr>
+ <th>Validator</th>
+ <th>Allowed datatypes</th>
+ </tr>
+ <tr>
+ <td>fd:assert</td>
+ <td>all datatypes</td>
+ </tr>
+ <tr>
+ <td>fd:email</td>
+ <td>string</td>
+ </tr>
+ <tr>
+ <td>fd:length</td>
+ <td>string</td>
+ </tr>
+ <tr>
+ <td>fd:mod10</td>
+ <td>string</td>
+ </tr>
+ <tr>
+ <td>fd:range</td>
+ <td>integer, long, decimal</td>
+ </tr>
+ <tr>
+ <td>fd:regexp</td>
+ <td>string</td>
+ </tr>
+ <tr>
+ <td>fd:value-count</td>
+ <td>all array types (use this with multivaluefield)</td>
+ </tr>
+ </table>
+ </s2>
- <s1 title="Description">
- <s2 title="assert">
+ <s2 title="fd:assert">
<p>Evaluates the expression specified in the "test" attribute. This
expression
should have a boolean result, it should evaluate to either true or
false.
Example: Suppose there are 2 fields widgets <code>password</code>
and <code>confirmPassword</code>.
@@ -94,14 +123,18 @@
</fd:assert>]]></source>
</s2>
- <s2 title="email">
+ <s2 title="fd:email">
<p>Checks that a value is a valid email address. Example:</p>
<source><![CDATA[<fd:email/>]]></source>
+
+ <p>Currently this checks the email does not contain any spaces,
+ contains exactly one <code>@</code> symbol with at least one
character
+ before it and at least one dot after it.</p>
</s2>
- <s2 title="length">
- <p>Checks the length of strings. This validation rule can take 3
attributes:
+ <s2 title="fd:length">
+ <p>Checks the length of strings. This validator can take 3
attributes:
min, max and exact. You can use either of these three separately or
min and max together. The values of these attributes are
expressions. Example:</p>
@@ -114,9 +147,9 @@
</fd:length>]]></source>
</s2>
- <s2 title="mod10">
+ <s2 title="fd:mod10">
<p>Uses the "mod10" algorithm used to check the validity of credit
card
- numbers such as VISA. This validation rule does not require any
additional
+ numbers such as VISA. This validator does not require any additional
attributes. Example:</p>
<source><![CDATA[<fd:mod10>
@@ -124,8 +157,8 @@
</fd:mod10>]]></source>
</s2>
- <s2 title="range">
- <p>Checks the numeric range. This validation rule can take 3
attributes:
+ <s2 title="fd:range">
+ <p>Checks the numeric range. This validator can take 3 attributes:
min, max and exact. You can use either of these three separately or
min and max together. The values of these attributes are
expressions. Example:</p>
@@ -136,7 +169,7 @@
<fd:range exact="2*2"/>]]></source>
</s2>
- <s2 title="regexp">
+ <s2 title="fd:regexp">
<p>Checks that a string matches a regular expression. It requires a
"pattern"
attribute specifying the regexp. The regular expression library used
is
Jakarta ORO, see <link
href="http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html";>here</link>
for some information. Example:</p>
@@ -146,7 +179,7 @@
</fd:regexp>]]></source>
</s2>
- <s2 title="value-count">
+ <s2 title="fd:value-count">
<p>Checks the number of items selected in a multivaluefield.
Again works with min, max and exact attributes. Example:</p>
@@ -155,6 +188,14 @@
Another example:
<fd:value-count exact="2"/>]]></source>
+ </s2>
+
+ <s2 title="fd:javascript">
+ <p>Allows to write a validator using Javascript, embedded directly
in the
+ form definition. The widget in question is available in the
Javascript
+ snippet as a variable called <code>widget</code>.</p>
+
+ <p>Checkout the samples of Cocoon for an example.</p>
</s2>
</s1>
</body>
1.3 +1 -1
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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- widget_field.xml 17 Apr 2004 17:19:59 -0000 1.2
+++ widget_field.xml 17 Apr 2004 18:29:28 -0000 1.3
@@ -29,7 +29,7 @@
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>
- <figure src="images/forms_field_datatype_relation.png" alt="Diagram
showing the associations between field, datatype, convertor, selection list and
validation rules."/>
+ <figure src="images/forms_field_datatype_relation.png" alt="Diagram
showing the associations between field, datatype, convertor, selection list and
validators."/>
<s2 title="Datatypes">
<p>A datatype represents a certain type of data, such as a
1.3 +1 -1
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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- widget_multivaluefield.xml 17 Apr 2004 17:19:59 -0000 1.2
+++ widget_multivaluefield.xml 17 Apr 2004 18:29:28 -0000 1.3
@@ -69,7 +69,7 @@
as for the <link href="widget_field.html">field</link> widget.</p>
<p>Note: A multivaluefield cannot have a required attribute,
- instead you should use the value-count validation rule to
+ instead you should use the value-count validator to
check the number of values the user has selected.</p>
</s1>
</body>
