Fields

The <field> element is used to specify the validation rules for a single input and to map the validation result to a form data property. After a form has successfully been validated, valid field values can populate their corresponding form data properties.

<field> elements may appear either as a children of a <form> element or inside <input> elements.

The <field> element requires the property attribute, giving the form data property name, to which this field maps. If the <field> is a direct <form> child, the property also gives th HTTP parameter name.

Actually, specifying a <field> element as a <form> child is just an abbreviated syntax for the common case, where a scalar input parameter is mapped to a single property with the same name. In other words, the form definitions

<form name="foo">
  <field property="bar">
    ...
  </field>
</form>

and

<form name="foo">
  <input name="bar">
    <field property="bar">
      ...
    </field>
  </input>
</form>

are equivalent.

The <field> element may contain

  1. a sequence of <match> elements, configuring the matchers to be used in the matching phase,
  2. a <convert> element, configuring the converter to be used in the converting phase,
  3. a sequence of <check> elements, configuring the checkers to be used in the checking phase,
  4. a <message> element, configuring a message to be generated when validation fails.

Field Validations

Field validations make use of validators, that have been declared inside the <validators> element (or of the predefined validators). Validations are applied in the order the corresponding elements appear inside the <field> element. Per definition, a field is valid, if all of its validations succeed.

All of the <match>, <convert> and <check> elements require the name attribute to reference a validator. They may contain <property> elements and a <message> element to customize the validator's properties and message.

Nested <property> elements can be used to set the validator properties, that it defines. A nested <message> element can be given to customize the validator's message.

For example, if a decimal input value shall be checked to be less than 10, the following field definition should be used:

<field property="bar">
  <convert name="decimal">
    <property name="maximumFractionDigits" value="2"/>
    <message>
      <arg name="field" value="Bar"/>
    </message>
  </convert>
  <check name="less">
    <property name="max" value="10.0"/>
    <message>
      <arg name="field" value="Bar"/>
    </message>
  </check>
</field>

We can "factor out" the common message argument named field and rewrite the above as:

<field property="bar">
  <convert name="decimal">
    <property name="maximumFractionDigits" value="2"/>
  </convert>
  <check name="less">
    <property name="max" value="10.0"/>
  </check>
  <message>
    <arg name="field" value="Bar"/>
  </message>
</field>

To make sure that a required date input is no Sunday, we write:

<field property="departure">
  <match name="notEmpty"/>
  <convert name="date"/>
  <check name="el">
    <property name="expression" value="property.day ne 0"/>
    <message bundle="foo.messages" key="error.check.noSunday">
      <arg value="Departure Date"/>
    </message>
  </check>
  <message>
    <arg name="field" value="Departure Date"/>
  </message>
</field>

By the way, the last example illustrated the use of an EL expression checker, which checks its expression to evaluate to true (the value to be checked is referred by the property variable, as usually the appending .day causes the getDay() method of our Date object to be called). The EL checker does usually require a custom message (since the expressions are not user-readable), so we add an entry like "error.check.noSunday=Field '{0}' must not contain a Sunday date" in our messages.properties file.