Added by Jeroen Reijn, last edited by Dennis Dam on Mar 28, 2008  (view change)

Labels:

types types Delete
templates templates Delete
htmlarea htmlarea Delete
validation validation Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Table of contents

Validating fields shown in the template.

To add validation to an element you will have to add a validation block to the rule. It should contain validation directives used to validate the contents of the field represented by the rule or type-rule.

<rule for="/root/title">
  <validation>
    <validator name="length" min="1" max="8"/>
  </validation>
</rule>

Inside the validation block you will need to define a validator block. The validator block defines the validation method used for this field. The value of the 'validator' element is used as a label for the validation error message. If you use i18n dictionaries, specify an i18n key here.

Attribute Name Description
name The name (type) of the validator. There are a number of types:
  • required (this field is required)
  • email (Tests whether the value of this field is a valid email address)
  • htmlarea-required ( Used for 'htmlfield' widgets. Tests whether the htmlfield contains contents. Another way to put it: makes an htmlfield 'required')
  • confirm ( Generates a copy of the presentation widget represented by this rule, which is used as a confirmation of the value. Helpful for password fields)
  • regexp ( Tests the value for a regular expression. Use the 'pattern' attribute to specify the regular expression.)
  • length ( Used for string values. Tests if the length of the string conforms to a minimum and/or maximum length. Use the 'min' and/or 'max' attributes to specify the minimum and maximum lengths)
  • assert ( Assertion of the value of this field. Use the 'expression' attribute to define the assertion expression)
  • javascript ( A custom validation in javascript. The contents of the validator element are interpreted as Cocoon flowscript code. You have to set the validation error message manually)
expression Used in combination with the 'assert' validator. Can only be used for simpleType elements, or attributes. An example of an expression: "${this} >= 0". ${this} refers to the value of the element/attribute.
min Used in combination with the 'length' validator. Tests whether the string value of the field is greater than or equal to the 'min' value.
max Used in combination with the 'length' validator. Tests whether the string value of the field is less than or equal to the 'max' value.
pattern Used in combination with the 'regexp' validator. Defines the regular expression for which the value of the field should be tested.

More about javascript (flowscript) validation

A javascript validator allows using a piece of flowscript to validate a field's value. Validation handlers only work for widgets, i.e. any field that is visible as an input field. This means it does not work on other elements, such as repeated elements which only have child elements. The flowscript is executed in an execution context in which there are several variables and helper functions available:

Variables

Variable Description Class
widget This is the Cocoon forms widget flowscript validation targets Depends on type of field, e.g. textfield is org.apache.cocoon.forms.formmodel.Field. See the org.apache.cocoon.forms.formmodel package API.
editorFlowContext Object holding information about the document currently being edited nl.hippo.cms.editor.flow.FlowContext

Functions

Function Description Return value
lookupWidget(widget,xpath) Returns a widget object, relative to the widget passed as first argument, using the relative/absolute xpath to that widget. the widget object if it exists, null otherwise
setValidationError(widget,error) Sets a validation error on a widget object, which will be displayed in the editor void
clearValidationError(widget) If you don't set a validation error, you have to call this function to clear previous validation errors void
validEmail(value) Convenience method. Checks on the email pattern true if the value matches to the email pattern
stringMatches(string,pattern) Convenience method. Checks if a string contains a (Java regexp) pattern true if the string matches the pattern.
strCompareIgnoreCase(a,b) Convenience method. Compares two values, case insensitive. true if the two values match

Examples

Field is required

<businesslogic>
  
  <rule for="/root/title">    
    <validation>
      <validator name="required">This field is required.</validator>
    </validation>
  </rule>

</businesslogic>

Regexp validation

In this example, only characters from a-z, A-Z, numbers from 0-9 and _ are allowed

<businesslogic>
  
  <rule for="/root/menu/level1/name">
    <validation>
      <validator name="regexp" pattern="[a-zA-Z0-9_]+">The menu name may only consist of the following characters: a..z A..Z 0..9 _</validator>
    </validation>  
  </rule>

</businesslogic>

Length validation

As you can see in the example below, the title field has to be between 1 and 8 characters long before the document is valid.

<businesslogic>
  
  <rule for="/root/title">    
    <validation>
      <validator name="length" min="1" max="8">This string has to be between 1 and 8 characters.</validator>
    </validation>
  </rule>

</businesslogic>

Email validation

The next example will show you how to validate an email field.

<businesslogic>
  
  <rule for="/root/email">    
    <validation>
      <validator name="email">This has to be a valid email address.</validator>
    </validation>
  </rule>

</businesslogic>

HtmlArea validation

<businesslogic>
  
  <rule for="/root/body">
    <binding-class>nl.hippo.cocoon.forms.binding.HTMLAreaBinding</binding-class>
    <convertor type="htmlcleaner" config="cocoon://editing/cf2/HtmlCleanerConfiguration.xml" use="datamodel"/>
    <validation>
      <validator name="htmlarea-required"/>
      <validator name="required"/>
    </validation>    
  </rule>  

</businesslogic>

Javascript validation

This example makes the field /root/foo required, only if the field /root/bar is non-empty:

<rule for="/root/foo">
  <validation>
    <validator name="javascript">
      <![CDATA[
        var barWidget = lookupWidget(widget,"/root/bar");      
        if (barWidget != null){
          if (barWidget.value != null && (widget.value == null || widget.value.length() <= 0)){
            setValidationError(widget,"This field is required when field 'bar' is not empty.");
            return false;
          }
        }
        
        clearValidationError(widget); // clear previous validation errors
        return true;           
      ]]>    
    </validator>
  </validation>
</rule>