husted 2002/12/27 03:15:06 Modified: doc/userGuide dev_validator.xml Log: Port David's overview -- these sections need to be reviewed in the context of the current codebase. Revision Changes Path 1.19 +401 -43 jakarta-struts/doc/userGuide/dev_validator.xml Index: dev_validator.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/userGuide/dev_validator.xml,v retrieving revision 1.18 retrieving revision 1.19 diff -u -r1.18 -r1.19 --- dev_validator.xml 27 Dec 2002 10:24:05 -0000 1.18 +++ dev_validator.xml 27 Dec 2002 11:15:06 -0000 1.19 @@ -34,34 +34,387 @@ </p> <p> - [:TODO: Cover basic functionality as documented on David's web site. - <a href="http://home.earthlink.net/~dwinterfeldt/">Validation Framework for - Struts </a>] + Once you have configured the Validator Plug-In, so that it can load your + Validator Resources you just have to extend + <code>org.apache.struts.validator.action.ValidatorForm</code> instead of + <code>org.apache.struts.action.ActionForm</code>. + Then when the <code>validate</code> method is called, the action's name + attribute from the struts-config.xml is used to load the validations for + the current form. + So the form element's <code>name</code> attribute in the + validator-rules.xml should match action element's <code>name</code> + attribute. + </p> + + <p> + Another alternative is to use the action mapping you are currently on by + extending the ValidatorActionForm instead of the ValidatorForm. + The ValidatorActionForm uses the action element's <code>path</code> + attribute from the struts-config.xml which should match the form element's + <code>name</code> attribute in the validator-rules.xml. + </p> + + <p> + Then a separate action can be defined for each page in a multi-page form + and the validation rules can be associated with the action and not a page + number as in the example of a multi-page form in the validator example. + </p> + +</section> + +<section href="i18n" name="Internationalization"> + + <p> + Validation rules for forms can be grouped under a <code>FormSet</code> + element in the validator-rules.xml file. + The <code>FormSet</code> has language, country, and variant attributes that + correspond with the <code>java.util.Locale</code> class. + If they are not used, the <code>FormSet</code> will be set to the default + locale. + A <code>FormSet</code> can also have constants associated with it. + On the same level as a <code>FormSet</code> there can be a global element + which can also have constants and have validator actions that perform + validations. + </p> + + <p> + The default error message for a pluggable validator can be overriden with + the <code>msg</code> element. + So instead of using the <code>msg</code> attribute for the mask validator + to generate the error message the <code>msg</code> attribute from the + field will be used if the name of the field's name attribute matches the + validator's name attribute. + </p> + +<pre><code><![CDATA[ +<field + property="lastName" + depends="required,mask"> + <msg + name="mask" + key="registrationForm.lastname.maskmsg"/> + <arg0 key="registrationForm.lastname.displayname"/> + <var> + <var-name>mask</var-name> + <var-value>^[a-zA-Z]*$</var-value> + </var> +</field> +]]></code></pre> + + <p> + The arguments for error messages can be set with the arg0-arg3 elements. + If the arg0-arg3 elements' name attribute isn't set, it will become the + default arg value for the different error messages constructed. + If the name attribute is set, you can specify the argument for a specific + pluggable validator and then this will be used for constructing the error + message. + </p> + +<pre><code><![CDATA[ +<field + property="lastName" + depends="required,mask"> + <msg + name="mask" + key="registrationForm.lastname.maskmsg"/> + <arg0 key="registrationForm.lastname.displayname"/> + <var> + <var-name>mask</var-name> + <var-value>^[a-zA-Z]*$</var-value> + </var> +</field> +]]></code></pre> + + <p> + By default the arg0-arg3 elements will try to look up the <code>key</code> + attribute in the message resources. + If the resource attribute is set to false, it will pass in the value directly + without retrieving the value from the message resources. + </p> + +<pre><code><![CDATA[ +<field + property="integer" + depends="required,integer,range"> + <arg0 key="typeForm.integer.displayname"/> + <arg1 + name="range" + key="${var:min}" + resource="false"/> + <arg2 + name="range" + key="${var:max}" + resource="false"/> + <var> + <var-name>min</var-name> + <var-value>10</var-value> + </var> + <var> + <var-name>max</var-name> + <var-value>20</var-value> + </var> + </field> +]]></code></pre> + +</section> + +<section href="members" name="Constants/Variables"> + + <p> + Global constants can be inside the global tags and FormSet/Locale + constants can be created in the formset tags. + Constants are currently only replaced in the Field's property attribute, + the Field's var element value attribute, the Field's msg element key + attribute, and Field's arg0-arg3 element's key attribute. + A Field's variables can also be substituted in the arg0-arg3 + elements (ex: ${var:min}). + The order of replacement is FormSet/Locale constants are replaced first, + Global constants second, and for the arg elements variables are replaced + last. + </p> + +<pre><code><![CDATA[ +<global> + <constant + name="zip" + value="^\d{5}(-\d{4})?$" /> +</global> + +<field + property="zip" + depends="required,mask"> +<arg0 key="registrationForm.zippostal.displayname"/> +<var> + <var-name>mask</var-name> + <var-value>${zip}</var-value> +</var> +</field> +]]></code></pre> + + <p> + The var element under a field can be used to store variables for use by a + pluggable validator. + These variables are available through the Field's + <code>getVar(String key)</code> method. + </p> + +<pre><code><![CDATA[ +<field + property="integer" + depends="required,integer,range"> + <arg0 key="typeForm.integer.displayname"/> + <arg1 + name="range" + key="${var:min}" + resource="false"/> + <arg2 + name="range" + key="${var:max}" + resource="false"/> + <var> + <var-name>min</var-name> + <var-value>10</var-value> + </var> + <var> + <var-name>max</var-name> + <var-value>20</var-value> + </var> + </field> +]]></code></pre> + +</section> + +<section href="plugs" name="Pluggable Validators"> + + <p> + Validation actions are read from the validation.xml file. + The default actions are setup in the validation.xml file. + The ones currently configured are required, mask ,byte, short, int, long, + float, double, date (without locale support), and a numeric range. + </p> + + <p> + The 'mask' action depends on required in the default setup. + That means that 'required' has to successfully completed before 'mask' will + run. + The 'required' and 'mask' action are partially built into the framework. + Any field that isn't 'required' will skip other actions if the field is null + or has a length of zero. + </p> + + <p> + If the <a href="struts-html.html#javascript">Javascript Tag</a> is used, + the client side Javascript eneration looks for a value in the validator's + javascript attribute and generates an object that the supplied method can + use to validate the form. + For a more detailed explanation of how the Javascript Validator Tag works, + see the <a href="struts-html.html">html taglib API reference</a>. + </p> + + + <p> + The 'mask' action lets you validate a regular expression mask to the field. + It uses the Regular Expression Package from the jakarta site. + All validation rules can be stored in the validator-rules.xml file. + The main class used is <code>org.apache.regexp.RE</code>. + </p> + + <p> + Example Validator Configuration from validation.xml. + </p> + +<pre><code><![CDATA[ +<validator name="required" + classname="org.apache.struts.validator.util.StrutsValidatorUtil" + method="validateRequired" + msg="errors.required"/> + +<validator name="mask" + classname="org.apache.struts.validator.util.StrutsValidatorUtil" + method="validateMask" + depends="required" + msg="errors.invalid"/> +]]></code></pre> + + <p> + <strong>Creating Pluggable Validators</strong> + </p> + + <p> + The ValidatorAction method needs to have the following signature. + </p> + +<pre><code><![CDATA[ +(java.lang.Object, + org.apache.commons.validator.ValidatorAction, + org.apache.commons.validator.Field, + org.apache.struts.action.ActionErrors, + javax.servlet.http.HttpServletRequest, + javax.servlet.ServletContext) +]]></code></pre> + + <ul> + + <li> + <code>java.lang.Object</code> + - Bean validation is being performed on. + </li> + + <li> + <code>org.apache.commons.validator.ValidatorAction</code> + - The current ValidatorAction being performed. + </li> + + <li> + <code>org.apache.commons.validator.Field</code> + - Field object being validated. + </li> + + <li> + <code>org.apache.struts.action.ActionErrors</code> + - The errors objects to add an ActionError to if the validation fails. + </li> + + <li> + <code>javax.servlet.http.HttpServletRequest</code> + - Current request object. + </li> + + <li> + <code>javax.servlet.ServletContext</code> + - The application's ServletContext. + </li> + + </ul> + + <p> + <strong>Multi Page Forms</strong> </p> -<p> -Changes in the validator behavior and deprecation of functionality from -original validator -</p> + <p> + The field element has an optional page attribute. + It can be set to an integer. + All validation for the any field page value less than or equal to the + current page is performed server side. + All validation for the any field page equal to the current page is + generated for the client side Javascript. + A mutli-part form expects the page attribute to be set. + </p> +<pre><code><![CDATA[ +<html:hidden property="page" value="1"/> +]]></code></pre> -<p> -Struts 1.1 has also added additional functionality over the original validator -contributed by David Winterfeldt. -</p> + <p> + <strong>Comparing Two Fields</strong> + </p> -<ul> + <p> + This is an example of how you could compare two fields to see if they + have the same value. + A good example of this is when you are validating a user changing their + password and there is the main password field and a confirmation field. + </p> -<li> -Conditionally required fields -</li> +<pre><code><![CDATA[ +<validator name="twofields" + classname="com.mysite.StrutsValidator" + method="validateTwoFields" + msg="errors.twofields"/> -<li> -<code>intRange</code> & <code>floatRange</code> methods in both JavaScript -and Java -</li> +<field property="password" + depends="required,twofields"> + <arg0 key="typeForm.password.displayname"/> + <var> + <var-name>secondProperty</var-name> + <var-value>password2</var-value> + </var> +</field> +]]></code></pre> -</ul> +<pre><code><![CDATA[ +public static boolean validateTwoFields( + Object bean, + ValidatorAction va, + Field field, + ActionErrors errors, + HttpServletRequest request, + ServletContext application) { + + String value = ValidatorUtil.getValueAsString( + bean, + field.getProperty()); + String sProperty2 = field.getVarValue("secondProperty"); + String value2 = ValidatorUtil.getValueAsString( + bean, + sProperty2); + + if (!GenericValidator.isBlankOrNull(value)) { + try { + if (!value.equals(value2)) { + errors.add(field.getKey(), + ValidatorUtil.getActionError( + application, + request, + va, + field)); + + return false; + } + } catch (Exception e) { + errors.add(field.getKey(), + ValidatorUtil.getActionError( + application, + request, + va, + field)); + return false; + } + } + + return true; +} +]]></code></pre> </section> @@ -92,6 +445,15 @@ <section href="validator-changes" name="Changes and deprecations"> <p> + <strong>New tag attributes.</strong> + </p> + + <p> + The <a href="struts-html.html#javascript"><html:javascript> tag</a> + has new attributes defined. + </p> + + <p> <strong>Validating against the DTD in the commons-validator.jar.</strong> </p> @@ -124,35 +486,15 @@ </p> <p> - <strong>New tag attributes.</strong> + <strong>New range methods.</strong> </p> <p> - The <a href="struts-html.html#javascript"><html:javascript> tag</a> - has new attributes defined. + <code>intRange</code> & <code>floatRange</code> methods in both + JavaScript and Java </p> <p> - <strong>Deprecations.</strong> - </p> - - <ul> - - <li> - Deprecation of <code>range</code> methods in both JavaScript and Java. - </li> - - <li> - Deprecation of StrutsValidator & StrutsValidatorUtil. - </li> - - </ul> - -</section> - -<section href="validator-new" name="New features"> - - <p> <strong>Conditionally required fields.</strong> </p> @@ -293,6 +635,22 @@ You can have an arbitrary number of fields by using the [n] syntax, the only restriction is that they must all be AND or OR, you can't mix. </p> + + <p> + <strong>Deprecations.</strong> + </p> + + <ul> + + <li> + Deprecation of <code>range</code> methods in both JavaScript and Java. + </li> + + <li> + Deprecation of StrutsValidator & StrutsValidatorUtil. + </li> + + </ul> </section>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>