Form validation in Cocoon can be achieved using two components:

As the form validator is a generic component it must be provided with parameters that describe the fields, and their validation routines for each form. The Action and the Logicsheet both process this description. This allows the action to apply the constraints, and the logicsheet to provide useful feedback to the user, i.e. what those constraints actually are.

Describing the Form

The XML file that describes form fields contains the following information:

XML file structure:

<root>
  <!-- field definitions -->
  <parameter name="" type="" nullable="" .../>
  <!-- constraint sets -->
  <constraint-set name="">
    <validate name=""/>
  </constraint-set>
</root>

Field Definitions

Constraints

The legal constraints are:

The constraints defined for individual parameters can be overridden within a particular constraint set.

Examples

<parameter name="username" type="string" nullable="no" min-len="5" max-len="10"/>
<parameter name="email" type="string" 
           max-len="50" 
           matches-regex="^[\d\w][\d\w\-_\.]*@([\d\w\-_]+\.)+(\w){2,4}$"/>

Additional Attributes

Additional attributes can be added to parameter definitions beyond the constraints specified above.

These will be ignored by the Form Validator Action, but are accessible using the Form Validator Logicsheet tags. This means that additional form-related parameters can be included in the descriptor and referenced from XSP pages, e.g. length of input fields, or other HTML form parameters.

Constraint Sets

A constraint set defines a named list of parameters that should be checked in one validation attempt. This avoids the need to explicitly list all parameters in the sitemap.

<constraint-set name="user">
  <validate name="username"/>
  <validate name="email"/>
</constraint-set>

Parameters defined in a constraint set can override constraints set globally in the main parameter definition. However all parameters must be declared separately before being used in a set.

There are also two additional attributes that can be specified on a validate element in a constraint-set.

Carrying out Validation

To carry out validation the FormValidatorAction requires two parameters:

<map:act type="form-validator">
  <parameter name="descriptor" value="context://descriptor.xml">
  <parameter name="validate" value="username,email">
</map:act>

<map:act type="form-validator">
  <parameter name="descriptor" value="context://descriptor.xml">
  <parameter name="validate-set" value="user">
</map:act>

This second form will test all parameters against the available descriptions. Request parameters not described in the constraint set will be ignored.

The action will return null if the validation fails, however an additional request parameter is added which describes the outcome of the validation. This parameter can be interpreted using the Form Validation Logicsheet.

Note: if a redirect is carried out at the end of the validation, then the results will be lost, although the original request parameters are retained.

Sitemap Example

<map:match pattern="target-for-form-POST">
  <map:act type="form-validator">
   <map:parameter name="descriptor" 
                  value="context://descriptor.xml"/>
   <map:parameter name="validate-set" 
                  value="constraint-set"/>
  <!-- do successful processing -->
  </map:act>
  <!-- do unsuccessful processing -->
</map:match>

Using the Logicsheet

As explained above the Form Validator Action adds a new request parameter that contains the results of the validation. The easiest way to interpret the results of processing is using the Form Validator Logicsheet from within an XSP page.

See XSPFormValidator Logicsheet for more information.

FormValidationUsingCocoon (last edited 2009-09-20 23:39:44 by localhost)