Using Form Validation
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation
XSP
XSP
XSP Internals
XSP Logicsheets
XSP Guide
Session Logicsheet
Sessions
Request Logicsheet
ESQL Logicsheet
Forms

Introduction

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.

This is about syntax checking. See org.apache.cocoon.acting.DatabaseAbstractAction (in javadocs) for details on database interaction.

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.

The Descriptor File

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.


<?xml version="1.0"?>
<root>

  <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?$">

  <constraint-set name="car-reservation">
    <validate name="persons"/>
    <validate name="deposit" min="50.0"/>
    <validate name="email"/>
  </constraint-set>

</root>

     

The above could for example describe expected input from a reservation form. Specifications in a constraint set take precedence over the general ones.


Sitemap Usage

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.


<?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>

     

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.


XSP Usage

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.

If only interested in validation results, just:


     <xsp-formval:on-ok name="persons">
       <myapp:error>(ERROR)</myapp:error>
     </xsp-formval:on-ok>

     

Alternatively, if you just want a boolean value from the logicsheet if a test is successful, use this method:


     <xsp:logic>
	 if (!<xsp-formval:is-ok name="persons"/>) {
	      <myapp:error>(ERROR)</myapp:error>
         };
     </xsp:logic>

     

Internationalization issues are a separate concern and are not discussed here.

Currently the following validation result codes are supported:

tag  Meaning 
xsp-formval:is-ok  no error occurred, parameter successfully checked 
xsp-formval:is-error  some error occurred, this is a result that is never set but serves as a comparison target  
xsp-formval:is-null  the parameter is null but isn't allowed to 
xsp-formval:is-toosmall  either value or length in case of a string is less than the specified minimum 
xsp-formval:is-toolarge  either value or length in case of a string is greater than the specified maximum 
xsp-formval:is-nomatch  a string parameter's value is not matched by the specified regular expression 
xsp-formval:is-notpresent  this is returned when the result of a validation is requested but no such result is found in the request attribute  

For debugging purposes or if you would like to iterate over the validation results, xsp-formval:results returns a java.util.Map containing them all.

If you would like to be more specific what went wrong, you can query the descriptor file for attributes.

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).

You need to do this only if you plan to query the descriptor file or if you'd like to use the shorthand below.


<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>

     

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.

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.


<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 (&lt; <xsp-formval:get-attribute name="min"/>))
      </myapp:error>
    } else if ( <xsp-formval:is-toolarge/> ) {
      <myapp:error>
        (deposit is too large (&gt; <xsp-formval:get-attribute name="max"/>))
      </myapp:error>
    } else {
      <myapp:error> (ERROR) </myapp:error>
    };
  </xsp:logic>
  </xsp-formval:validate>
</xsp-formval:descriptor>

     


Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.