haul 2002/08/11 11:38:04
Modified: src/java/org/apache/cocoon/acting FormValidatorAction.java
src/documentation/xdocs/userdocs/xsp logicsheet-forms.xml
src/documentation/xdocs/userdocs/concepts modules.xml
Log:
Update docs
Revision Changes Path
1.11 +3 -3
xml-cocoon2/src/java/org/apache/cocoon/acting/FormValidatorAction.java
Index: FormValidatorAction.java
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/java/org/apache/cocoon/acting/FormValidatorAction.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- FormValidatorAction.java 9 Aug 2002 08:27:18 -0000 1.10
+++ FormValidatorAction.java 11 Aug 2002 18:38:04 -0000 1.11
@@ -260,11 +260,11 @@
if (!allOK) {
// if any validation failed return an empty map
actionMap = null;
- resultMap.put("*", new ValidatorActionHelper(null,
ValidatorActionResult.ERROR));
+ resultMap.put("*", ValidatorActionResult.ERROR);
if (getLogger().isDebugEnabled())
getLogger().debug ("All form params validated. An error
occurred.");
} else {
- resultMap.put("*", new ValidatorActionHelper(null,
ValidatorActionResult.OK));
+ resultMap.put("*", ValidatorActionResult.OK);
if (getLogger().isDebugEnabled())
getLogger().debug ("All form params successfully validated");
}
1.2 +336 -162
xml-cocoon2/src/documentation/xdocs/userdocs/xsp/logicsheet-forms.xml
Index: logicsheet-forms.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/xsp/logicsheet-forms.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- logicsheet-forms.xml 3 Jan 2002 12:31:06 -0000 1.1
+++ logicsheet-forms.xml 11 Aug 2002 18:38:04 -0000 1.2
@@ -2,42 +2,181 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
- <header>
- <title>Using Form Validation</title>
- <version>0.1</version>
- <type>Overview document</type>
- <authors>
- <person name="Christian Haul" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Introduction">
+ <header>
+ <title>Using Form Validation</title>
+ <version>0.2</version>
+ <type>Overview document</type>
+ <authors>
+ <person name="Christian Haul" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Introduction">
+
+ <p>
+ For most web applications input is essential. Apache Cocoon provides a
+ variety of modules to support basic interaction like simple syntax checking
+ of input data or writing input data to databases.
+ </p>
+
<p>
- For most web applications input is essential. Apache Cocoon provides a
- variety of modules to support basic interaction like simple syntax
- checking of input data or writing input data to databases.
+ Two different packages deal with validating user input:<link
+ href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">XMLForm</link>
+ which tries to stay as close as possible with the <link
+ href="www.w3.org">W3C</link> <link
+ href="http://www.w3.org/MarkUp/Forms/";>XForms</link> working draft.
+ Another, simpler and older implementation is the validation using the
+ <code>FormValidatorAction</code>, which is described here.
</p>
+
<p>
- This is about syntax checking. See
- org.apache.cocoon.acting.DatabaseAbstractAction (in javadocs) for
- details on database interaction.
+ To validate user input, an action, the <code>FormValidatorAction</code>, is
+ placed in your pipeline. Together with a descriptor file, that specifies
+ the allowed input, this action validates the request parameters. Based on
+ the result, a different page can be displayed and feedback can be given to
+ the user either using XSP and the <code>formval</code> logicsheet or the
+ <code>SimpleFormTransformer</code>.
</p>
+
+ <s2 title="Sitemap Usage">
+ <p>
+ To take advantage of the form validator action, create two pages. One for
+ the input form and one indicating the acceptance of the reservation.
+ Create a pipeline in your sitemap so that the confirmation page is only
+ shown when the action completed successfully and the input form is
+ returned otherwise.
+ </p>
+
+ <source>
+<![CDATA[
+<?xml version="1.0"?>
+ <map:match pattern="car-reservation">
+ <map:act type="form-validator">
+ <!-- add you favourite database action here -->
+ <map:parameter name="descriptor" value="descriptor.xml"/>
+ <map:parameter name="validate-set" value="car-reservation"/>
+ <map:generate type="serverpages" src="OK.xsp"/>
+ <map:transform src="stylesheets/dynamic-page2html.xsl"/>
+ <map:serialize/>
+ </map:act>
+ <map:generate type="serverpages" src="test/ERROR.xsp"/>
+ <map:transform src="stylesheets/dynamic-page2html.xsl"/>
+ <map:serialize/>
+ </map:match>
+]]>
+ </source>
+
+ <p>
+ Note here that you may not use a redirection to point to the pages if you
+ would like to access the validation results e.g. on the error page. A
+ redirection would create a new request object and thus discard the
+ validation results.
+ </p>
+
<p>
- FormValidatorAction communicates to the application a verbose
- error status through an request attribute. In addition a taglib
- allows easy access to the results. On top of that this taglib
- gives access to the attributes for parameters declared in those
- sections in descriptor.xml relevant to the validation process.
- </p>
- <s2 title="The Descriptor File">
- <p>
- For details on the syntax of the descriptor file see
- javadocs. Basically it consists of two sections, a list of
- parameters and their properties and a list of constraints or
- constraint sets. The file syntax is set up so that it can be
- shared with the database actions.
+ A different example, that does not need serverpages but the
+ <code>SimpleFormTransformer</code>:
</p>
- <source>
+
+ <source>
+<![CDATA[
+<?xml version="1.0"?>
+ <map:match pattern="car-reservation">
+ <map:act type="req-params">
+ <map:parameter name="parameters" value="order"/>
+
+ <map:act type="form-validator">
+ <map:parameter name="descriptor" value="descriptor.xml"/>
+ <map:parameter name="validate-set" value="car-reservation"/>
+ <!-- add you favourite database action here -->
+
+ <map:generate type="file" src="OK.xml"/>
+ <map:transform src="stylesheets/dynamic-page2html.xsl"/>
+ <map:serialize/>
+ </map:act>
+ </map:act>
+ <map:generate type="file" src="test/ERROR.xml"/>
+ <map:transform src="stylesheets/dynamic-page2html.xsl"/>
+ <map:transform type="simple-form"/>
+ <map:serialize/>
+ </map:match>
+]]>
+ </source>
+
+ <p>
+ Although this looks more complicated at first, it has advantages if you
+ don't want to or cannot use XSP. For example, if the form is stored as
+ XHTML in a database, XSP could not be used to fill the form with values
+ from request parameters or to display detailed error messages.
+ </p>
+ <note>
+ Keep in mind that files, here the descriptor file, could be specified
+ using the <code>cocoon:</code> pseudo-protocol. Thus the file could be
+ generated dynamically from another pipeline!
+ </note>
+
+ </s2>
+
+ <s2 title="The Descriptor File">
+
+ <p>
+ For details on the syntax of the descriptor file see javadocs. Basically
+ it consists of two sections, a list of parameters and their properties and
+ a list of constraints or constraint sets. The file syntax is set up so
+ that it can be shared with the database actions.
+ </p>
+
+ <s3 title="The types recognized by validator and their attributes"/>
+ <table>
+ <tr>
+ <td><b>string</b></td><td>nullable="yes|no" default="str"</td>
+ </tr>
+ <tr>
+ <td><b>long</b></td><td>nullable="yes|no" default="123123"</td>
+ </tr>
+ <tr>
+ <td><b>double</b></td><td>nullable="yes|no" default="0.5"</td>
+ </tr>
+ </table>
+
+ <p>
+ Default value takes place only when specified parameter is nullable and
+ really is null or empty. Long numbers may be specified in decimal, hex or
+ octal values as accepted by java.Lang.decode (String s).
+ </p>
+
+ <s3 title="Constraints"/>
+ <table>
+ <tr>
+ <td>matches-regex</td><td>POSIX regular expression</td>
+ </tr>
+ <tr>
+ <td>one-of</td><td>List of strings, enclosed and separated by
<code>|</code></td>
+ </tr>
+ <tr>
+ <td>min-len</td><td>positive integer</td>
+ </tr>
+ <tr>
+ <td>max-len</td><td>positive integer</td>
+ </tr>
+ <tr>
+ <td>min</td><td>Double / Long</td>
+ </tr>
+ <tr>
+ <td>max</td><td>Double / Long</td>
+ </tr>
+ </table>
+ <p>
+ Constraints can be defined globally for a parameter and can be overridden
+ by redefinition in a constraint-set. Thus if e.g. a database field can take
+ at maximum 200 character, this property can be set globally.
+ </p>
+ <p>
+ Values in parameter arrays are validated individually and the worst
+ error is reported back.
+ </p>
+
+ <source>
<![CDATA[
<?xml version="1.0"?>
<root>
@@ -45,7 +184,8 @@
<parameter name="persons" type="long" min="1" default="4" nullable="no"/>
<parameter name="deposit" type="double" min="10.0" max="999.99"/>
<parameter name="email" type="string" max-len="50"
- matches-regex="^[\d\w][\d\w\-_\.]*@([\d\w\-_]+\.)\w\w\w?$">
+ matches-regex="^[\d\w][\d\w\-_\.]*@([\d\w\-_]+\.)\w\w\w?$"/>
+ <parameter name="colour" type="string" one-of="|red|green|blue|white|"/>
<constraint-set name="car-reservation">
<validate name="persons"/>
@@ -55,158 +195,125 @@
</root>
]]>
- </source>
+ </source>
+
<p>
- The above could for example describe expected input from a reservation
- form. Specifications in a constraint set take precedence over
- the general ones.
- </p>
- </s2>
- <s2 title="Sitemap Usage">
- <p>
- To take advantage of the form validator action create two
- pages. One for the input form and one indicating the acceptance of
- the reservation. Create a pipeline in your sitemap so that the
- confirmation page is only shown when the action completed
- successfully and the input form is returned otherwise.
+ The above could for example describe expected input from a reservation
+ form. Specifications in a constraint set take precedence over the general
+ ones.
</p>
- <source>
-<![CDATA[
-<?xml version="1.0"?>
- <map:match pattern="car-reservation">
- <map:act type="form-validator">
- <!-- add you favourite database action here -->
- <map:parameter name="descriptor" value="descriptor.xml"/>
- <map:parameter name="validate-set" value="car-reservation"/>
- <map:generate type="serverpages" src="OK.xsp"/>
- <map:transform src="stylesheets/dynamic-page2html.xsl"/>
- <map:serialize/>
- </map:act>
- <map:generate type="serverpages" src="test/ERROR.xsp"/>
- <map:transform src="stylesheets/dynamic-page2html.xsl"/>
- <map:serialize/>
- </map:match>
-]]>
- </source>
- <p>
- Note here that you may not use a redirection to point to the
- pages if you would like to access the validation results e.g. on
- the error page. A redirection would create a new request object
- and thus discard the validation results.
- </p>
- </s2>
- <s2 title="XSP Usage">
- <p>
- To give the user some feedback why her/his submitted data was rejected
- there is a special taglib "xsp-formval". Declare its name space as
- usual.
+
+ </s2>
+
+
+ <s2 title="XSP Usage">
+
+ <p>
+ To give the user some feedback why her/his submitted data was rejected
+ there is a special taglib "xsp-formval". Declare its name space as usual.
</p>
+
<p>
- If only interested in validation results, just:
+ If only interested in validation results, just:
</p>
- <source>
+
+ <source>
<![CDATA[
<xsp-formval:on-ok name="persons">
<myapp:error>(ERROR)</myapp:error>
</xsp-formval:on-ok>
]]>
- </source>
- <p>
- Alternatively, if you just want a boolean value from the logicsheet
- if a test is successful, use this method:
- </p>
- <source>
+ </source>
+
+ <p>
+ Alternatively, if you just want a boolean value from the logicsheet if a
+ test is successful, use this method:
+ </p>
+
+ <source>
<![CDATA[
<xsp:logic>
- if (!<xsp-formval:is-ok name="persons"/>) {
- <myapp:error>(ERROR)</myapp:error>
+ if (!<xsp-formval:is-ok name="persons"/>) {
+ <myapp:error>(ERROR)</myapp:error>
};
</xsp:logic>
]]>
- </source>
- <p>
- Internationalization issues are a separate concern and are not
- discussed here.
- </p>
- <p>
+ </source>
+
+ <p>
+ Internationalization issues are a separate concern and are not discussed
+ here.
+ </p>
+ <p>
Currently the following validation result codes are supported:
- </p>
- <table>
- <tr><th>tag</th><th>Meaning</th></tr>
- <tr><td>xsp-formval:is-ok</td><td>no error occurred,
- parameter successfully
- checked</td></tr>
- <tr><td>xsp-formval:is-error</td><td>some error occurred,
- this is a result that
- is never set but serves
- as a comparison target
- </td></tr>
- <tr><td>xsp-formval:is-null</td><td>the parameter is null but
- isn't allowed to</td></tr>
- <tr><td>xsp-formval:is-toosmall</td><td>either value or
- length in case of a
- string is less than
- the specified
- minimum</td></tr>
- <tr><td>xsp-formval:is-toolarge</td><td>either value or
- length in case of a
- string is greater
- than the specified
- maximum</td></tr>
- <tr><td>xsp-formval:is-nomatch</td><td>a string parameter's
- value is not matched
- by the specified
- regular expression</td></tr>
- <tr><td>xsp-formval:is-notpresent</td><td>this is returned
- when the result of
- a validation is
- requested but no
- such result is
- found in the
- request attribute </td></tr>
- </table>
- <p>
- For debugging purposes or if you would like to iterate over the
- validation results, <code>xsp-formval:results</code> returns a
+ </p>
+
+ <table>
+ <tr><th>tag</th><th>Meaning</th></tr>
+ <tr><td>xsp-formval:is-ok</td><td>no error occurred, parameter
+ successfully checked</td></tr>
+ <tr><td>xsp-formval:is-error</td><td>some error occurred, this is a result
+ that is never set but serves as a comparison target
+ </td></tr>
+ <tr><td>xsp-formval:is-null</td><td>the parameter is null but
+ isn't allowed to</td></tr>
+ <tr><td>xsp-formval:is-toosmall</td><td>either value or length in case of
+ a string is less than the specified minimum</td></tr>
+ <tr><td>xsp-formval:is-toolarge</td><td>either value or length in case of
+ a string is greater than the specified maximum</td></tr>
+ <tr><td>xsp-formval:is-nomatch</td><td>a string parameter's value is not
+ matched by the specified regular expression</td></tr>
+ <tr><td>xsp-formval:is-notpresent</td><td>this is returned when the result
+ of a validation is requested but no such result is found in the request
+ attribute </td></tr>
+ </table>
+
+ <p>
+ For debugging purposes or if you would like to iterate over the validation
+ results, <code>xsp-formval:results</code> returns a
<code>java.util.Map</code> containing them all.
- </p>
- <p>
- If you would like to be more specific what went wrong, you can
- query the descriptor file for attributes.
- </p>
- <p>
- First set the url of the file or resource that contains the
- parameter descriptions and constraint sets. This needs to be an
- ancestor to all other tags (of this taglib). Multiple use of this
- tag is allowed (although probably not necessary).
- </p>
- <p>
- You need to do this only if you plan to query the
- descriptor file or if you'd like to use the shorthand
- below.
- </p>
- <source>
+ </p>
+
+ <p>
+ If you would like to be more specific what went wrong, you can query the
+ descriptor file for attributes.
+ </p>
+
+ <p>
+ First set the url of the file or resource that contains the parameter
+ descriptions and constraint sets. This needs to be an ancestor to all
+ other tags (of this taglib). Multiple use of this tag is allowed (although
+ probably not necessary).
+ </p>
+
+ <p> You need to do this only if you plan to query the descriptor file or if
+ you'd like to use the shorthand below.
+ </p>
+
+ <source>
<![CDATA[
<xsp-formval:descriptor name="descriptor.xml" constraint-set="reservation">
deposit must be at least EUR
<xsp-formval:get-attribute parameter="deposit" name="min"/>
</xsp-formval:descriptor>
]]>
- </source>
- <p>
- If you need to use one parameter a lot, there's a short hand. Use
- this e.g. if you'd like to set up the properties of an input tag
- according to the information from the descriptor file or if you'd
- like to give detailed error messages.
- </p>
- <p>
- Note that you can specify additional attributes in the
- description file that are not understood (and therefore ignored)
- by the FormValidatorAction but that could be queried here. This
- might be e.g. the size of the input field which might be
- different from the max-len a parameter can take.
- </p>
- <source>
+ </source>
+
+ <p>
+ If you need to use one parameter a lot, there's a short hand. Use this
+ e.g. if you'd like to set up the properties of an input tag according to
+ the information from the descriptor file or if you'd like to give detailed
+ error messages.
+ </p>
+
+ <p>
+ Note that you can specify additional attributes in the description file
+ that are not understood (and therefore ignored) by the FormValidatorAction
+ but that could be queried here. This might be e.g. the size of the input
+ field which might be different from the max-len a parameter can take.
+ </p>
+
+ <source>
<![CDATA[
<xsp-formval:descriptor name="descriptor.xml" constraint-set="car-reservation">
<xsp-formval:validate name="deposit">
@@ -228,9 +335,76 @@
</xsp-formval:validate>
</xsp-formval:descriptor>
]]>
- </source>
- </s2>
+ </source>
+
+ </s2>
+
+ <s2 title="SimpleFormTransformer">
+
+ <p>
+ An alternative solution to using the <code>formval</code> logicsheet and
+ XSP is to use the <code>SimpleFormTransformer</code>. If fills the form
+ with values obtained from request parameters, overwriting existing
+ values. Hence the data entered by the user is not discarded when it does
+ not validate successfully.
+ </p>
+
+ <note>
+ Beware when using the <code>SimpleFormTransformer</code> together with
+ XSP: The observer behaviour can be very confusing when trying to set a
+ value from XSP and it is silently overwritten by the transformer!
+ </note>
+
+ <p>
+ When a form element carries the attribute <code>fixed="true"</code>, the
+ transformer does not replace the value.
+ </p>
+
+ <p>
+ Feedback can be given to the user through <code><error/></code>
+ tags. Error tags need to have a name attribute identical to the input
+ element they refer to. Multiple error elements may be present for any
+ input element. The <code>FormValidatorAction</code> sets a special field
+ <code>*</code> that indicates whether all parameters were validated
+ successfully or not.
+ </p>
+
+ <p>
+ An error element is omitted together with all contents whenever the
+ specified condition is not met. Conditions are either exact or greater
+ equal constraints indicated by the attribute <code>when</code> or
+ <code>when-ge</code> respectively.
+ </p>
+
+ <p>
+ Allowed values for error conditions are: <code>ok, not-present, error,
+ is-null, too-small, too-large, no-match </code>
+ </p>
+
+ <source>
+<![CDATA[
+ <input name="email" type="text"/><error name="email" when-ge="error">*</error>
+ <!-- ... -->
+ <error name="email" when="is-null">Please enter your email address.</errro>
+ <error name="email" when="no-match">Please enter a <em>syntacticly</em> correct
+ email address.</errro>
+]]>
+ </source>
+ </s2>
+
+ <s2 title="Other Validations">
+
+ <p>
+ In addition to validating form input, other actions exists that validate
+ values from different sources using the same techniques and syntax. For
+ example, the <code>SessionValidatorAction</code> operates on session
+ attributes.
+ </p>
+
+ </s2>
+
</s1>
+
</body>
</document>
1.3 +4 -4
xml-cocoon2/src/documentation/xdocs/userdocs/concepts/modules.xml
Index: modules.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/concepts/modules.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- modules.xml 25 Jun 2002 09:37:05 -0000 1.2
+++ modules.xml 11 Aug 2002 18:38:04 -0000 1.3
@@ -27,10 +27,6 @@
Developing With Apache Avalon</fork>. It is a very good description
of the underlying rationale and principles.
</p>
- <note>
- To use modules, Apache Cocoon needs to have been build to include
- scratchpad components.
- </note>
</s1>
<s1 title="Types of Modules">
<p>
@@ -153,6 +149,10 @@
declared above allows to override the skin with a request
parameter
named "skin".
</p>
+ <note>
+ The above sitemap syntax is only available with the 2.1-dev
version
+ of Apache Cocoon.
+ </note>
<source>
<![CDATA[
<map:transform src="resources/stylesheets/{default:skin}.xsl"/>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
