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.

Table 20-1: Validator Configuration File Tags

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., arg0arg3) 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>



Struts. The Complete Reference
Struts: The Complete Reference, 2nd Edition
ISBN: 0072263865
EAN: 2147483647
Year: 2004
Pages: 165
Authors: James Holmes

Similar book on Amazon
Struts 2 in Action
Struts 2 in Action
Murach's Java Servlets and JSP, 2nd Edition
Murach's Java Servlets and JSP, 2nd Edition
Jakarta Struts For Dummies
Jakarta Struts For Dummies
Head First Servlets and JSP: Passing the Sun Certified Web Component Developer Exam
Head First Servlets and JSP: Passing the Sun Certified Web Component Developer Exam

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net