To validate the inputs for a specific action you add a filter named forms to the action's definition:

<calyxo-control-config version="0.9"
  xmlns="http://calyxo.odysseus.de/xml/ns">
	
  ...

  <action path="/foo" source="page" target="page">
    <filter name="forms">
      <param name="form" value="fooForm"/>
      <param name="class" value="java.util.HashMap"/>
      <param name="attribute" value="fooData"/>
      <dispatch path="/WEB-INF/jsp/foo.jsp"/>
    </filter>
    ...
  </action>

  ...

</calyxo-control-config>

There are the following filter parameters:

form

Required. Determines the validation form, where the validation rules for this action are defined. The referred form has to be added to the Calyxo Forms configuration file (or to one of the files, which are imported by the configuration file).

dispatch

Optional. The name of the dispatch configuration used by the filter when form validation fails. If omitted, a nested anonymous <dispatch> element is required.

class

Optional. The fully qualified Java class to be used for the form data object, if none is found under the specified attribute name. The form data object is explained in more detail in the next section.

attribute

Optional. The name under which the form data is stored.

scope

Optional (requires the attribute parameter to be specified, too). The scope, where the form data is stored under the specified attribute name. Default value is session, alternatively you can choose request.

commit

Optional. A boolean value, which determines whether the validated form properties are automatically committed, i.e. stored in the form data, or not. (Default is false.)

The validated input properties are accessible via an instance of de.odysseus.calyxo.forms.FormProperties, which is made available to your execute(...) method as described in the next section. The form properties offer a getProperty(String name) method to access an input property by name and a commit() method, which is used to populate the form data with the values from the form properties, if they passed all additional checks performed by your action. The form data object is an instance of the de.odysseus.calyxo.forms.FormData interface. This interface provides the property accessor methods _getProperty(String name) and _setProperty(String name, Object value). When you specify your form data class (using the forms filter parameter named class), you have three possibilities:

• Your class may implement the FormData interface. In this case the form data object is simply an instance of the specified class, as you would expect.
• Your class may implement the java.util.Map interface. This causes the instance of the specified class to be wrapped in a de.odysseus.calyxo.forms.misc.FormDataMap object. This wrapper implements the FormData interface and gives access to the values of the contained map.
• Otherwise, we assume a bean and wrap the instance of the specified class in a de.odysseus.calyxo.forms.misc.FormDataBean object. As above, this wrapper implements the FormData interface and gives access to the properties of the contained bean.

In the latter two cases you can access the wrapped object (i.e., the map or the bean) using the _getWrapped() method provided by the FormData interface.

When writing your action class, you have two choices:

• You may subclass the convenience class de.odysseus.calyxo.forms.control.FormsAction, which itself is a subclass of de.odysseus.calyxo.control.misc.AbstractAction, (described in the Calyxo Control documentation). The FormsAction class adds the convenience method getFormsSupport(), which gives you an easy way to receive an appropriate instance of the utility class de.odysseus.calyxo.forms.control.FormsSupport, allowing you to handle the form properties, form data and form result in your action. Besides this, the FormsAction class replaces the abstract execute(...) method by an extended version, taking the form properties as an additional argument. It does now look like this:

  public abstract DispatchConfig execute(
    HttpServletRequest request,
    HttpServletResponse response,
    FormProperties formProperties) throws Exception;
  

  This way you have your form properties at hand when writing your execute(...) method, and thus all of the validated property values from your input form.
• If you prefer just to implement the de.odysseus.calyxo.control.Action interface (as described in the Calyxo Control documentation), you'll usually need to access your form properties, too. Then the above mentioned FormsAction class can give you a hint how to access it: just copy the code into your (root) action class and go ahead.