Editing Validator Configuration Files with Struts Console
The Validator Configuration File Tags
Table 20-1 lists each of the tags used to configure the Validator configuration file and provides a short description of each tag's purpose.
| Tag | Description |
|---|---|
| arg | Defines a parametric replacement value (e.g., {0}, {1}, {2}, and so on) for a validation's error message. |
| constant | Defines a named value that can be used as a replacement parameter within the field tag's nested tags. |
| constant-name | Defines the constant tag's constant name. |
| constant-value | Defines the constant tag's constant value. |
| field | Defines the set of validations that will be applied to a form's field. |
| form | Defines a Form Bean whose set of fields will be validated based on rules defined by nested field tags. |
| form-validation | Is the root tag for the Validator configuration file and thus encapsulates all other tags in the file. |
| formset | Defines validations for a set of forms. |
| global | Encapsulates the set of validations and the set of constants that Validator will use. |
| javascript | Defines client-side JavaScript code for a validation. |
| msg | Defines an error message that will override a validation's default message. |
| validator | Defines a validation routine and assigns it a logical name. |
| var | Defines a variable that will be passed to each of a field's validators at run time. |
| var-jstype | Defines the var tag's JavaScript type. |
| var-name | Defines the var tag's variable name. |
| var-value | Defines the var tag's variable value. |
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 the given attribute is required when using the tag. In addition to the required column denoting whether an attribute is required, the rows for required attributes are highlighted in gray so that you can determine at a glance which attributes are required. 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 arg Tag
The arg tag is used to define a parametric replacement value (e.g., {0}, {1}, {2}, and so on) for a validation's error message. 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 the arg tag. Thus, if "Username" was specified with the arg tag, the preceding message would be turned into the following message:
Username is a required field
| Note | In previous versions of Validator there were multiple arg tags (i.e., arg0–arg3) that were used to specify the parametric replacement values. The multiple tags were deprecated and eventually removed in favor of having a single arg tag with a position attribute so that an endless number of parametric values could be specified. Before only replacement values 0–3 could be specified. |
DTD Definition
Following is the definition for the arg tag from the Validator configuration file DTD:
<!ELEMENT arg EMPTY>
Attributes
| Attribute | Description | Required |
|---|---|---|
| bundle | Specifies the logical name of a resource bundle that will be used when looking up the message key specified by the key attribute. | No |
| key | Specifies a key for a resource bundle message that will be used as the replacement value. | Yes |
| name | Specifies the logical name of the validation that this tag will be applied to. | No |
| position | Specifies the position of the parametric replacement value (e.g., 0, 1, 2, etc.). | No |
| resource | Accepts true or false to specify whether the key attribute's value will not be taken as a literal value rather than a message key. Defaults to true. | No |
Example Usage
The following example illustrates the basic usage of the arg tag:
<field property="zipCode" depends="required,mask"> <arg position="0" key="prompt.zipCode"/> <var> <var-name>mask</var-name> <var-value>\>^\d{5}\d*$</var-value> </var> </field> This example specifies the {0} 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:
<arg position="0" 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, a constant 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-value>^\d{5}\d*$</constant-value> </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|arg|var)*>
Attributes
| Attribute | Description | Required |
|---|---|---|
| depends | Specifies the comma-delimited list of validations that will be applied to this field. | No |
| indexedListProperty | Specifies the name of a collection field whose elements will be validated. If this attribute is specified, the value specified with the property attribute will be used as the name of the property that will be validated on each object in the collection. | No |
| page | Specifies a value that will be compared against the enclosing Form Bean's page property if it has one. If the value if less than or equal to the Form Bean's page property, then this field definition's validations will be applied. If not, they will be bypassed. This feature is useful for wizard-style forms where fields need to be conditionally validated based on which page the wizard is on currently. | No |
| property | Specifies the name of the form field. | Yes |
Example Usage
The following example illustrates the basic usage of the field tag:
<field property="zipCode" depends="required,mask"> <arg position="0" 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 arg, 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*)>
Attributes
| Attribute | Description | Required |
|---|---|---|
| extends | Specifies the name of another form that this form extends. | No |
| name | Specifies the name of the form. | Yes |
Example Usage
The following snippet illustrates how to use the form tag:
<form name="logonForm"> <field property="username" depends="required"> <arg position="0" key="prompt.username"/> </field> <field property="password" depends="required"> <arg position="0" 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, language, and variant attributes to tailor a set of validations to a specific locale. The formset definition without a country, language, or variant attribute specified is considered the default set of validations. Any other formset definitions with one or multiple 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
| Attribute | Description | Required |
|---|---|---|
| country | Specifies the locale country code that this form set's definitions will be applied to. | No |
| language | Specifies the locale language code that this form set's definitions will be applied to. | No |
| variant | Specifies the locale variant that this form set's definitions will be applied to. | No |
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, language, and variant 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, language, and variant attributes can be used together 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.ActionMessages, org.apache.commons.validator.Validator, 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.
| Note | This example of using the <javascript> tag is for illustration purposes and does not exactly match the actual definition for the minlength validation. In the latest versions of Validator, all of the JavaScript code has been removed from the validator-rules.xml file and moved into separate .js files (e.g., validateMinLength.js). The file the JavaScript version of a routine is stored in is specified with the jsFunction attribute of the <validator> tag using a fully qualified path to the file. However, if you want to override the default JavaScript code provided by a validation routine or are adding your own validation routine with associated JavaScript code, you can use the <javascript> tag as shown. |
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
| Attribute | Description | Required |
|---|---|---|
| bundle | Specifies the logical name of a resource bundle that will be used when looking up the message key specified by the key attribute. | No |
| key | Specifies a resource bundle message key that the specified validation will use for its error message instead of its default message. | Yes |
| name | Specifies the logical name of the validation whose error message will be overridden. | No |
| resource | Accepts true or false to specify whether the key attribute's value will not be taken as a literal value rather than a message ey. Defaults to true. | No |
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"/> <arg position="0" 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
| Attribute | Description | Required |
|---|---|---|
| classname | Specifies the name of the class that houses the validation routine. | Yes |
| depends | Specifies a comma-delimited list of other validations defined by the validator tag that must pass before this validation is executed. | No |
| jsFunction | Specifies the JavaScript method name for this validation routine. | No |
| jsFunctionName | Specifies an alternate method name to use for the JavaScript code generated by this tag if client-side validation is enabled. | No |
| method | Specifies the name of the validation routine's method in the class specified by the classname attribute. | Yes |
| methodParams | Specifies the comma-delimited list (in order) of the validation routine's arguments. | Yes |
| msg | Specifies a resource bundle message key for the error message that will be generated if this validation fails. | Yes |
| name | Specifies the logical name for the validation. | Yes |
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.ActionMessages, org.apache.commons.validator.Validator, 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 arg and msg tags, as shown here:
<arg position="0" 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, value, and JavaScript type are defined with nested var-name, var-value, and var-jstype tags, respectively.
DTD Definition
Following is the definition for the var tag from the Validator configuration file DTD:
<!ELEMENT var (var-name,var-value,var-jstype?)>
Example Usage
The following snippet illustrates how to use the var tag:
<field property="username" depends="required,maxlength"> <arg position="0" 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-jstype Tag
The var-jstype tag is used to define the var tag's JavaScript type. This tag must be nested exactly once underneath the var tag or not at all. The JavaScript type specifies the data type of the variable that will be created in the client-side JavaScript version of the validation routine. There are three acceptable values for the type: int, string, and regexp.
DTD Definition
Following is the definition for the var-jstype tag from the Validator configuration file DTD:
<!ELEMENT var-jstype (#PCDATA)>
Example Usage
The following snippet illustrates how to use the var-jstype tag:
<field property="username" depends="required,maxlength"> <arg position="0" key="prompt.username"/> <var> <var-name>maxlength</var-name> <var-value>16</var-value> <var-jstype>int</var-jstype> </var> </field>
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"> <arg position="0" 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"> <arg position="0" key="prompt.username"/> <var> <var-name>maxlength</var-name> <var-value>16</var-value> </var> </field>
EAN: 2147483647
Pages: 165