Forms

A Validation Form definition contains all the information required to validate the input data contained in a form. On the one hand these are single-field validation rules (expressed via validators), on the other hand we have multiple-field validation rules (expressed via assertions).

These form definitions are contained in the <forms> section of a Calyxo Forms configuration file. (Actually, there may be more than one <forms> section for different locales, but for the sake of simplicity we assume a single <forms> section here.)

A form definition consists of two parts (both of which may be empty). It starts with the single-field validation rules defined in <field> and <input> elements, followed by the multiple-field validation rules defined in <assert> elements. Let's look at an example:

<form name="orForm">

  <field property="date1">
    <convert name="date">
      <message>
        <arg name="field" value="date1"/>
      </message>
    </convert>
  </field>

  <field property="date2">
    <convert name="date">
      <message>
        <arg name="field" value="date2"/>
      </message>
    </convert>
  </field>

  <assert test="not empty input.date1 or not empty input.date2">
    <message bundle="messages" key="error.or">
      <arg value="date1"/>
      <arg value="date2"/>
    </message>
  </assert>

</form>

Here we have two input properties, date1 and date2, which are converted from input strings into date values using the date converter. If one of the inputs can not be parsed as a date, a suitable error message specifying the input field is generated. If both inputs are valid (i.e., none of their validators failed), the assertion assures that not both of them are empty (empty inputs do not cause the date converter to fail, it simply converts them into a null date). If the assertion fails, it generates a custom error message, which might be defined as "error.or=At least one of '{0}' and '{1}' must be entered". Only when the input passes all validators and assertions, the converted values are stored in the form properties and the action, which caused the validation, is executed.