Struts: The Complete Reference, 2nd Edition

Table 18-1 lists each of the tags used to configure the Validator configuration file and provides a short description of each tag's purpose.

The remainder of this chapter discusses each tag in detail, including a complete description of the tag, the tag's DTD definition, a table that lists each of the tag's attributes (if the tag has attributes), and a usage example for the tag. In the tables that describe a tag's attributes, pay special attention to the Required column, which denotes whether or not the given attribute is required when using the tag. If an attribute is required and you do not specify it when using the tag, the Validator framework will not be properly configured and, consequently, will not function properly.

The arg0, arg1, arg2, and arg3 Tags

The arg tags are used to define values for a validation's error message. There are four arg tags and they are shown here:

• arg0  The first replacement value, specified by {0}

• arg1  The second replacement value, specified by {1}

• arg2  The third replacement value, specified by {2}

• arg3  The fourth replacement value, specified by {3}

Before the specified validation's error message is generated, it is parsed and any {N} reference is replaced with the message specified by the corresponding tag. Following is an example resource bundle message that contains a {0} reference:

errors.required={0} is a required field

At run time, when Validator uses this error message, it will attempt to replace any parametric references with the values specified by their respective arg0 - arg3 tags. Thus, if 'Username' was specified with the arg0 tag, the preceding message would be turned into the following message:

Username is a required field

DTD Definition

Following is the definition for the arg tags from the Validator configuration file DTD:

<!ELEMENT argN EMPTY>

Attributes

Example Usage

The following example illustrates the basic usage of the arg2 tag:

<field property="zipCode"        depends="required,mask">  <arg2 key="prompt.zipCode"/>  <var>    <var-name>mask</var-name>    <var-value>>^\d{5}\d*$</var-value>  </var> </field>

This example specifies the {2} replacement value to use for each of the validations specified by the field tag's depends attribute. Alternatively, the arg tag can be configured to apply to only a specific validation's error message by using the name attribute, as shown next:

<arg2 name="required" key="prompt.zipCode"/>

In this example, the replacement value will be applied only to the required validation's error message.

The constant Tag

The constant tag is used to define a named value that can be used as a replacement parameter within the field tag's nested tags. For example, constants can be used to define an often used regular expression for the configurable mask validation, as shown here:

<constant>  <constant-name>zip</constant-name>  <constant-phone>^\d{5}\d*$</constant-phone> </constant>

Each time a ZIP code needs to be validated with the mask validation, the constant can be used to specify the regular expression to use, instead of having to specify the regular expression itself, as shown next:

<field property="zipCode"        depends="required,mask">  <var>    <var-name>mask</var-name>    <var-value>${zip}</var-value>  </var> </field>

To use constants, you simply enclose the constant name with an opening ${ and a closing }.

DTD Definition

Following is the definition for the constant tag from the Validator configuration file DTD:

<!ELEMENT constant (constant-name, constant-value)>

Example Usage

The following snippet illustrates how to use the constant tag:

<global>  <constant>    <constant-name>zip</constant-name>    <constant-value>^\d{5}\d*$</constant-value>  </constant> </global>

The constant tag can be used an unlimited number of times. Each use of the constant tag must have nested constant-name and constant-value tags.

The constant-name Tag

The constant-name tag is used to define the constant tag's constant name. This tag must be nested exactly once underneath the constant tag.

DTD Definition

Following is the definition for the constant-name tag from the Validator configuration file DTD:

<!ELEMENT constant-name (#PCDATA)>

Example Usage

The following snippet illustrates how to use the constant-name tag:

<global>  <constant>    <constant-name>zip</constant-name>    <constant-value>^\d{5}\d*$</constant-value>  </constant> </global>

The constant-value Tag

The constant-value tag is used to define the constant tag's constant value. This tag must be nested exactly once underneath the constant tag.

DTD Definition

Following is the definition for the constant-value tag from the Validator configuration file DTD:

<!ELEMENT constant-value (#PCDATA)>

Example Usage

The following snippet illustrates how to use the constant-value tag:

<global>  <constant>    <constant-name>zip</constant-name>    <constant-value>^\d{5}\d*$</constant-value>  </constant> </global>

The field Tag

The field tag is used to define the set of validations that will be applied to a form's field.

DTD Definition

Following is the definition for the field tag from the Validator configuration file DTD:

<!ELEMENT field (msg|arg0|arg1|arg2|arg3|var)*>

Attributes

Example Usage

The following example illustrates the basic usage of the field tag:

<field property="zipCode"        depends="required,mask">  <arg0 key="prompt.zipCode"/>  <var>    <var-name>mask</var-name>    <var-value>>^\d{5}\d*$</var-value>  </var> </field>

Each validation specified with the depends attribute will be executed in order. Consequently, if a validation fails, the remaining validations will be skipped. Additionally, each validation can be globally or individually customized with nested arg0 - arg3, msg, and var tags.

The form Tag

The form tag is used to define a Form Bean whose set of fields will be validated based on rules defined by nested field tags.

DTD Definition

Following is the definition for the form tag from the Validator configuration file DTD:

<!ELEMENT form (field+)>

Attribute

Example Usage

The following snippet illustrates how to use the form tag:

<form name="logonForm">  <field property="username" depends="required">    <arg0 key="prompt.username"/>  </field>  <field property="password" depends="required">    <arg0 key="prompt.password"/>  </field> </form>

The name specified with the name attribute must match the logical name of a Form Bean from the Struts configuration file. Similarly, each of the form's nested field tags must match a property of the Form Bean.

The form-validation Tag

The form-validation tag is the root tag for the Validator configuration file and thus encapsulates all other tags in the file. This tag has no other use than to denote the beginning and end of configuration data.

DTD Definition

Following is the definition for the form-validation tag from the Validator configuration file DTD:

<!ELEMENT form-validation (global*,formset*)>

Example Usage

The following snippet illustrates how to use the form-validation tag:

<form-validation>  <global>    …  </global>  <formset>    …  </formset> </form-validation>

The formset Tag

The formset tag is used to define validations for a set of forms. By default, the validations are applied to the enclosing forms for users within any locale. However, you can optionally use the country and language attributes to tailor a set of validations to a specific locale. The formset definition without the country or language attribute specified is considered the default set of validations. Any other formset definitions with one or both of the locale-narrowing attributes will override any overlapping forms. That is, if the default (or master) form set defines three forms and a locale-specific form set overrides one of the forms for French users, only the one form will be overridden for French users-not every form defined by the default form set.

DTD Definition

Following is the definition for the formset tag from the Validator configuration file DTD:

<!ELEMENT formset (constant*, form+)>

Attributes

Example Usage

The following example illustrates the basic usage of the formset tag:

<formset>  <form name="logonForm">    …  </form>  <form name="searchForm">    …  </form> </formset>

Because this example omits the country and language attributes, the enclosed validations will be applied to users within any locale unless specifically overridden with other formset definitions.

If desired, one or more forms' validations can be overridden by specifying additional form sets for specific locales, as shown next:

<formset language="fr">  <form name="logonForm">    …  </form> </formset>

This example provides validation settings for all users whose locale has French as its language. The country and language attributes can be used in tandem or individually based on how specific or broad the validation settings will be.

The global Tag

The global tag is used to encapsulate the set of validations and the set of constants that Validator will use. This tag is simply a container for validator and constant tags.

DTD Definition

Following is the definition for the global tag from the Validator configuration file DTD:

<!ELEMENT global (validator*, constant*)>

Example Usage

The following example illustrates the basic usage of the global tag:

<global>  <constant>    <constant-name>zip</constant-name>    <constant-value>^\d{5}\d*$</constant-value>  </constant> </global>

The javascript Tag

The javascript tag is used to define client-side JavaScript code for a validation. The code placed between opening and closing javascript tags will be used to perform a preliminary client-side (browser) validation if Validator is configured to do so.

DTD Definition

Following is the definition for the javascript tag from the Validator configuration file DTD:

<!ELEMENT javascript (#PCDATA)>

Example Usage

The following example illustrates how to use the javascript tag:

<validator name="minlength"      classname="org.apache.struts.validator.FieldChecks"         method="validateMinLength"   methodParams="java.lang.Object,                 org.apache.commons.validator.ValidatorAction,                 org.apache.commons.validator.Field,                 org.apache.struts.action.ActionErrors,                 javax.servlet.http.HttpServletRequest"            msg="errors.minlength">  <javascript>    <![CDATA[      function validateMinLength(form) {        var isValid = true;        var focusField = null;        var i = 0;        var fields = new Array();        oMinLength = new minlength();        for (x in oMinLength) {          var field = form[oMinLength[x][0]];          if (field.type == 'text' ||              field.type == 'textarea') {            var iMin = parseInt(oMinLength[x][2]("minlength"));            if ((trim(field.value).length > 0) &&                (field.value.length < iMin)) {              if (i == 0) {                focusField = field;              }              fields[i++] = oMinLength[x][1];              isValid = false;            }          }        }        if (fields.length > 0) {          focusField.focus();          alert(fields.join('\n'));        }        return isValid;      }    ]]>  </javascript> </validator>

Notice that the JavaScript code is enclosed in a <![CDATA[ ]]> tag. This is an XML facility that is used to notify XML parsers that the enclosed text should be taken as is and should not be parsed. Normally, parsers would parse the text for other tags or XML entities; however, sometimes it's necessary to specify text that has XML-like references in it, but that should not be parsed. The <![CDATA[ ]]> tag makes that possible.

The msg Tag

The msg tag is used to define an error message that will override a validation's default message. When validations are defined with the validator tag, they define a resource bundle message key for an error message that will be used when the validation fails. Sometimes, however, it's necessary to use an error message other than the default for a validation. The msg tag makes this possible by allowing for an alternative message to be set for a specific use of the validation.

DTD Definition

Following is the definition for the msg tag from the Validator configuration file DTD:

<!ELEMENT msg EMPTY>

Attributes

Example Usage

The following example illustrates the basic usage of the msg tag:

<field property="ssNum"        depends="required,mask">  <msg name="mask" key="errors.ssNum"/>  <arg0 key="ssNum.prompt"/>  <var>    <var-name>mask</var-name>    <var-value></var-value>  </var> </field>

In this example, the mask validation is overridden to use the errors.ssNum message key instead of the one defined by the validation. As you can see, the msg tag is useful for specifying custom error messages for validations.

The validator Tag

The validator tag is used to define a validation routine and assign it a logical name. Each definition specifies the Java class, method, and method arguments for the validation routine. Once defined, the validation routine can be applied to form fields using its logical name.

DTD Definition

Following is the definition for the validator tag from the Validator configuration file DTD:

<!ELEMENT validator (javascript?)>

Attributes

Example Usage

The following example illustrates the basic usage of the validator tag:

<validator name="minlength"      classname="org.apache.struts.validator.FieldChecks"         method="validateMinLength"   methodParams="java.lang.Object,                 org.apache.commons.validator.ValidatorAction,                 org.apache.commons.validator.Field,                 org.apache.struts.action.ActionErrors,                 javax.servlet.http.HttpServletRequest"            msg="errors.minlength"/>

Each validation definition specifies the Java class, method, and method arguments for the validation. Validator uses reflection to instantiate and invoke the validation at run time.

The var Tag

The var tag is used to define a variable that will be passed to each of a field's validations at run time. This allows validations to be configurable. For example, the maximum length validation has a variable that specifies its maximum length that must be set using this tag. Additionally, variables defined with the var tag can be used by the arg0 - arg3 and msg tags, as shown here:

<arg1 name="maxlength" key="${var:maxlength}" resource="false"/>

To reference variables defined by the var tag from other tags, you must use this form: ${var:varName} (where varName is the name of the defined variable).

The variable's name and value are defined with nested var-name and var-value tags, respectively.

DTD Definition

Following is the definition for the var tag from the Validator configuration file DTD:

<!ELEMENT var (var-name,var-value)>

Example Usage

The following snippet illustrates how to use the var tag:

<field property="username"        depends="required,maxlength">  <arg0 key="prompt.username"/>  <var>    <var-name>maxlength</var-name>    <var-value>16</var-value>  </var> </field>

The var tag can be nested underneath the field tag an unlimited number of times. Each use of the var tag must have nested var-name and var-value tags.

The var-name Tag

The var-name tag is used to define the var tag's variable name. This tag must be nested exactly once underneath the var tag.

DTD Definition

Following is the definition for the var-name tag from the Validator configuration file DTD:

<!ELEMENT var-name (#PCDATA)>

Example Usage

The following snippet illustrates how to use the var-name tag:

<field property="username"        depends="required,maxlength">  <arg0 key="prompt.username"/>  <var>    <var-name>maxlength</var-name>    <var-value>16</var-value>  </var> </field>

The var-value Tag

The var-value tag is used to define the var tag's variable value. This tag must be nested exactly once underneath the var tag.

DTD Definition

Following is the definition for the var-value tag from the Validator configuration file DTD:

<!ELEMENT var-value (#PCDATA)>

Example Usage

The following snippet illustrates how to use the var-value tag:

<field property="username"        depends="required,maxlength">  <arg0 key="prompt.username"/>  <var>    <var-name>maxlength</var-name>    <var-value>16</var-value>  </var> </field>