dims 01/06/19 04:45:38
Modified: xdocs docs-book.xml site-book.xml
Added: xdocs logicsheet-forms.xml
Log:
Added Form Validation docs from Christian.
Revision Changes Path
1.8 +1 -0 xml-cocoon2/xdocs/docs-book.xml
Index: docs-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/docs-book.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- docs-book.xml 2001/06/19 11:25:21 1.7
+++ docs-book.xml 2001/06/19 11:45:37 1.8
@@ -27,6 +27,7 @@
<page id="logicsheet-sessions" label="Session Logicsheet" source="session.xml"/>
<page id="logicsheet-request" label="Request Logicsheet" source="request.xml"/>
<page id="logicsheet-esql" label="ESQL Logicsheet" source="esql.xml"/>
+ <page id="logicsheet-forms" label="Forms" source="logicsheet-forms.xml"/>
<separator/>
<external label="XML Links"
href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/"/>
<separator/>
1.11 +1 -0 xml-cocoon2/xdocs/site-book.xml
Index: site-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/site-book.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- site-book.xml 2001/06/19 11:25:22 1.10
+++ site-book.xml 2001/06/19 11:45:37 1.11
@@ -31,6 +31,7 @@
<page id="logicsheet-sessions" label="Session Logicsheet" source="session.xml"/>
<page id="logicsheet-request" label="Request Logicsheet" source="request.xml"/>
<page id="logicsheet-esql" label="ESQL Logicsheet" source="esql.xml"/>
+ <page id="logicsheet-forms" label="Forms" source="logicsheet-forms.xml"/>
<separator/>
<external href="apidocs/index.html" label="API (Javadoc)"/>
<separator/>
1.1 xml-cocoon2/xdocs/logicsheet-forms.xml
Index: logicsheet-forms.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "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?">
<p>
For most web applications input is essential. 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>
This is about syntax checking. See
org.apache.cocoon.acting.DatabaseAbstractAction (in javadocs) for
details on database interaction.
</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 constists 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>
<source>
<![CDATA[
<?xml version="1.0"?>
<root>
<parameter name="persons" type="long" min="1" default="4"/>
<parameter name="deposit" type="double" min="10.0" max="999.99" nullable="no"/>
<parameter name="email" type="string" max-len="50"
match-regex="^[\d\w][\d\w\-_\.]*@([\d\w\-_]+\.)\w\w\w?$">
<constraint-set name="car-reservation">
<validate name="persons"/>
<validate name="deposit" min="50.0"/>
<validate name="email"/>
</constraint-set>
</root>
]]>
</source>
<p>
The aboce could for example describe expected input from a reservation
form. Specifications in a constraint set take preceedence 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.
</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.
</p>
<p>
If only interested in validation results, just
</p>
<source>
<![CDATA[
<xsp:logic>
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>
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>
If you'd 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>
<![CDATA[
<xsp-formval:descriptor name="descriptor.xml" constraint-set="car-reservation">
<xsp-formval:validate name="deposit">
<xsp:logic>
if (<xsp-formval:is-null/>) {
<myapp:error> (you must specify a deposit)) </myapp:error>
} else if ( <xsp-formval:is-toosmall/> ) {
<myapp:error> (deposit is too small (< <xsp-formval:get-attribute
name="min"/>))</myapp:error>
} else if ( <xsp-formval:is-toolarge/> ) {
<myapp:error> (deposit is too large (> <xsp-formval:get-attribute
name="max"/>))</myapp:error>
} else {
<myapp:error> (ERROR) </myapp:error>
};
</xsp:logic>
</xsp-formval:validate>
</xsp-formval:descriptor>
]]>
</source>
</s2>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
