dwinterfeldt 01/10/21 20:43:56 Modified: contrib/validator/docs overview.html jsptags.html installation.html Log: Updated documentation. Revision Changes Path 1.2 +223 -63 jakarta-struts/contrib/validator/docs/overview.html Index: overview.html =================================================================== RCS file: /home/cvs/jakarta-struts/contrib/validator/docs/overview.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- overview.html 2001/07/09 02:55:37 1.1 +++ overview.html 2001/10/22 03:43:56 1.2 @@ -12,7 +12,7 @@ <table border=0 cellpadding=4 cellspacing=0 width=100% bgcolor="0000AA"><tr><td> <table border=0 cellpadding=1 cellspacing=0 width=100% bgcolor=FFFFFF><tr width=100%><td> <font size=+3>Struts Validator</font> - <BR> + <br> <font size=+1>Validation Framework for Struts</font> </td></tr></table> </td></tr></table> @@ -49,9 +49,22 @@ </td> <!-- Body --> <td valign="top"> - <H2>Overview</H2> + <p> + <a href="#overview">Overview</a><br> + <a href="#setup">Setup</a><br> + <a href="#i18n">Internationalization</a><br> + <a href="#constantsAndVars">Constants/Variables</a><br> + <a href="#validators">Pluggable Validators</a><br> + <a href="#creatingValidators">Creating Pluggable Validators</a><br> + <a href="#multiPageForms">Multi Page Forms</a><br> + <a href="#comparingTwoFields">Comparing Two Fields</a><br> + <a href="#validatingOutsideOfStruts">Validating Outside of Struts</a><br> + </p> + + <H2><a name="overview">Overview</a></H2> <p>The Validation Framework was made to work with - <a href="http://jakarta.apache.org/struts">Struts</a>. It can perform basic + <a href="http://jakarta.apache.org/struts">Struts</a>, but can be used for validation of any + java bean. It can perform basic validations to check if a field is required, matches a regular expression, email, credit card, and server side type checking and date validation. Different validation rules can be defined for different locales. The framework has basic support for @@ -59,8 +72,28 @@ are modifiable in the validation.xml file so custom validation routines can be created and added to the framework. </p> + + <H3><a name="setup">Setup</a></H3> + <p>In Struts once you have defined the ValidatorServlet in the web.xml so it can + load your ValidatorResources you just have to extend + com.wintecinc.struts.action.ValidatorForm instead of + org.apache.struts.action.ActionForm. Then when the validate 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 name attribute in + the validation.xml should match action element's name 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 'path' attribute from the + struts-config.xml which should match the form element's name attribute + in the validation.xml. 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> - <H3>Internationalization</H3> + <H3><a name="i18n">Internationalization</a></H3> <p>Validation rules for forms can be grouped under a FormSet in the validation.xml file. The FormSet has language, country, and variant attributes that correspond with the java.util.Locale class. If they are not used, the FormSet will be set to the default locale. @@ -70,12 +103,14 @@ </p> <p>The default error message for a pluggable validator can be overriden with the - msg element.<BR> - <BR> - ex: <field property="lastName" <BR> - depends="required,mask"> <BR> - <msg name="mask" key="registrationForm.lastname.maskmsg"/> <BR> - <arg0 key="registrationForm.lastname.displayname"/> <BR> + msg element. So instead of using the msg attribute for the mask validator to generate the + error message the msg attribute from the field will be used if the name of the field's name + attribute matches the validator's name attribute.<br> + <br> + ex: <field property="lastName" <br> + depends="required,mask"> <br> + <msg name="mask" key="registrationForm.lastname.maskmsg"/> <br> + <arg0 key="registrationForm.lastname.displayname"/> <br> <var><br> <var-name>mask</var-name><br> <var-value>^[a-zA-Z]*$</var-value><br> @@ -87,12 +122,12 @@ 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.<BR> - <BR> - ex: <field property="lastName" <BR> - depends="required,mask"> <BR> - <msg name="mask" key="registrationForm.lastname.maskmsg"/> <BR> - <arg0 key="registrationForm.lastname.displayname"/> <BR> + used for constructing the error message.<br> + <br> + ex: <field property="lastName" <br> + depends="required,mask"> <br> + <msg name="mask" key="registrationForm.lastname.maskmsg"/> <br> + <arg0 key="registrationForm.lastname.displayname"/> <br> <var><br> <var-name>mask</var-name><br> <var-value>^[a-zA-Z]*$</var-value><br> @@ -103,13 +138,13 @@ <p>By default the arg0-arg3 elements will try to look up the key 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.<BR> - <BR> - ex: <field property="integer" <BR> - depends="required,integer,range"><BR> - <arg0 key="typeForm.integer.displayname"/><BR> - <arg1 name="range" key="${var:min}" resource="false"/><BR> - <arg2 name="range" key="${var:max}" resource="false"/><BR> + value directly without retrieving the value from the message resources.<br> + <br> + ex: <field property="integer" <br> + depends="required,integer,range"><br> + <arg0 key="typeForm.integer.displayname"/><br> + <arg1 name="range" key="${var:min}" resource="false"/><br> + <arg2 name="range" key="${var:max}" resource="false"/><br> <var><br> <var-name>min</var-name><br> <var-value>10</var-value><br> @@ -118,24 +153,24 @@ <var-name>max</var-name><br> <var-value>20</var-value><br> </var><br> - </field><BR> + </field><br> </p> - <H3>Constants/Variables</H3> + <H3><a name="constantsAndVars">Constants/Variables</a></H3> <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.<BR> - ex: <global> <BR> - <constant name="zip" value="^\d{5}(-\d{4})?$" /> <BR> - </global> <BR> - <BR> - <field property="zip"<BR> - depends="required,mask"><BR> - <arg0 key="registrationForm.zippostal.displayname"/><BR> + arg elements variables are replaced last.<br> + ex: <global> <br> + <constant name="zip" value="^\d{5}(-\d{4})?$" /> <br> + </global> <br> + <br> + <field property="zip"<br> + depends="required,mask"><br> + <arg0 key="registrationForm.zippostal.displayname"/><br> <var><br> <var-name>mask</var-name><br> <var-value>${zip}</var-value><br> @@ -145,13 +180,13 @@ <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 getVar(String key) method.<BR> - ex: <BR> - <field property="integer" <BR> - depends="required,integer,range"><BR> - <arg0 key="typeForm.integer.displayname"/><BR> - <arg1 name="range" key="${var:min}" resource="false"/><BR> - <arg2 name="range" key="${var:max}" resource="false"/><BR> + validator. These variables are available through the Field's getVar(String key) method.<br> + ex: <br> + <field property="integer" <br> + depends="required,integer,range"><br> + <arg0 key="typeForm.integer.displayname"/><br> + <arg1 name="range" key="${var:min}" resource="false"/><br> + <arg2 name="range" key="${var:max}" resource="false"/><br> <var><br> <var-name>min</var-name><br> <var-value>10</var-value><br> @@ -160,14 +195,14 @@ <var-name>max</var-name><br> <var-value>20</var-value><br> </var><br> - </field><BR> - <BR> + </field><br> + <br> <font size=-1><i>See type form's integer field in the example web app for a working example.</i></font> </p> - <H3>Pluggable Validators</H3> + <H3><a name="validators">Pluggable Validators</a></H3> <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), @@ -189,26 +224,27 @@ <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">org.apache.regexp.RE</a>. </p> - <p>Example Validator Configuration from validation.xml.<BR> - <validator name="required"<BR> - classname="com.wintecinc.struts.validation.Validator"<BR> - method="validateRequired"<BR> - msg="errors.required"/><BR> - <BR> - <validator name="mask"<BR> - classname="com.wintecinc.struts.validation.Validator"<BR> - method="validateMask"<BR> - depends="required"<BR> - msg="errors.invalid"/><BR> + <p>Example Validator Configuration from validation.xml.<br> + <validator name="required"<br> + classname="com.wintecinc.struts.validation.Validator"<br> + method="validateRequired"<br> + msg="errors.required"/><br> + <br> + <validator name="mask"<br> + classname="com.wintecinc.struts.validation.Validator"<br> + method="validateMask"<br> + depends="required"<br> + msg="errors.invalid"/><br> </p> - <H3>Creating Pluggable Validators</H3> - <p>The ValidatorAction method needs to have the following signature. - <BR> - (java.lang.Object, <BR> - com.wintecinc.struts.validation.ValidatorAction, com.wintecinc.struts.validation.Field, <BR> - org.apache.struts.action.ActionErrors, , <BR> - javax.servlet.http.HttpServletRequest, javax.servlet.ServletContext)<BR> + <H3><a name="creatingValidators">Creating Pluggable Validators</a></H3> + <p>The ValidatorAction method needs to have the following signature. See the + com.wintecinc.struts.validation.StrutsValidator class for examples.<br> + <br> + (java.lang.Object, <br> + com.wintecinc.struts.validation.ValidatorAction, com.wintecinc.struts.validation.Field, <br> + org.apache.struts.action.ActionErrors, , <br> + javax.servlet.http.HttpServletRequest, javax.servlet.ServletContext)<br> <table> <tr><td><b>java.lang.Object</b></td><td>Bean validation is being performed on.</td></tr> <tr><td><b>com.wintecinc.struts.validation.ValidatorAction</b></td><td>The current ValidatorAction being performed.</td></tr> @@ -219,13 +255,137 @@ </table> </p> - <H3>Multi Page Forms</H3> + <H3><a name="multiPageForms">Multi Page Forms</a></H3> <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.<BR> + Javascript. A mutli-part form expects the page attribute to be set.<br> ex: <html:hidden property="page" value="1"/> </p> + + <H3><a name="comparingTwoFields">Comparing Two Fields</a></H3> + <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> + <p> + <validator name="twofields"<br> + classname="com.mysite.StrutsValidator"<br> + method="validateTwoFields"<br> + msg="errors.twofields"/> + </p> + <p> + <field property="password"<br> + depends="required,twofields"><br> + <arg0 key="typeForm.password.displayname"/><br> + <var><br> + <var-name>secondProperty</var-name><br> + <var-value>password2</var-value><br> + </var><br> + </field><br> + </p> + <p> + public static boolean validateTwoFields(Object bean, <br> + ValidatorAction va, Field field, <br> + ActionErrors errors, <br> + HttpServletRequest request, ServletContext application) {<br> + <br> + String value = ValidatorUtil.getValueAsString(bean, field.getProperty());<br> + String sProperty2 = field.getVarValue("secondProperty");<br> + String value2 = ValidatorUtil.getValueAsString(bean, sProperty2);<br> + <br> + if (!GenericValidator.isBlankOrNull(value)) {<br> + try {<br> + if (!value.equals(value2)) {<br> + errors.add(field.getKey(), ValidatorUtil.getActionError(application, request, va, field));<br> + <br> + return false;<br> + }<br> + } catch (Exception e) {<br> + errors.add(field.getKey(), ValidatorUtil.getActionError(application, request, va, field));<br> + return false;<br> + }<br> + }<br> + <br> + return true;<br> + }<br> + </p> + + <H3><a name="validatingOutsideOfStruts">Validating Outside of Struts</a></H3> + <p>Here is a short example of validating something outside of the Struts Framework. + The validator element's methodParams attribute have a default method signature + that all the StrutsValidator validation methods use. + </p> + <p> + <form-validation> <br> + <global> <br> + <validator name="capLetter"<br> + classname="com.mysite.Validator"<br> + methodParams="java.lang.Object,com.wintecinc.struts.validation.Field,java.util.List"<br> + method="isCapLetter"<br> + msg="Letter is not in upper case."/><br> + </global> <br> + <formset> <br> + <form name="testForm"><br> + <field property="letter" <br> + depends="capLetter"> <br> + </field><br> + </form><br> + </formset> <br> + </form-validation> <br> + + </p> + <p>The method signature and parameters are dynamically created based on + the methodParams and the resources added to the Validator using the + class name as a key. The class "java.lang.Object" is reserved for the + bean that is being validated and there can't be any duplicate class names + because they are used as the key when associating the actual instance + of the class when setting up the Validator. + </p> + <p> + The ValidatorAction and the Field are automatically passed in if specified in the + methodParams attribute. The other instances of classes need to be added to the + Validator using the addResource method along with the class they represent from + the validator element's methodParams attribute. Bean is the object + being validated. The ValidatorResourcesInitializer can be used to load + the validation.xml file and return an instance of ValidatorResources based on + the xml file. So based on the validation.xml file defined above the + getLetter method will be called on the bean variable.<br> + <br> + ValidatorResources resources = ValidatorResourcesInitializer.initialize("validation.xml", debug);<br> + Validator validator = new Validator(resources, "testForm");<br> + validator.addResource(Validator.BEAN_KEY, bean);<br> + validator.addResource("java.util.List", lErrors);<br> + <br> + try { <br> + validator.validate(); <br> + } catch (ValidatorException e) { <br> + // Log Exception <br> + }<br> + </p> + <p>This is the validation method being used by the capLetter validator. The + validation fails if the value retrieved is null, has a length other than one, + and the character doesn't fall in the range A-Z. Error messages are added to + the java.util.List that is passed into the method.<br> + <br> + public static boolean isCapLetter(Object bean, Field field, List l) { <br> + String value = ValidatorUtil.getValueAsString(bean, field.getProperty()); <br> + <br> + if (value != null && value.length() == 1) { <br> + if (value.charAt(0) >= 'A' && value.charAt(0) <= 'Z') { <br> + return true; <br> + } else { <br> + l.add(field.getMsg); <br> + return false; <br> + } <br> + } else { <br> + l.add(field.getMsg); <br> + return false; <br> + } <br> + } + </p> + <p> </p> </td> <!-- / Body --> </tr> 1.2 +16 -4 jakarta-struts/contrib/validator/docs/jsptags.html Index: jsptags.html =================================================================== RCS file: /home/cvs/jakarta-struts/contrib/validator/docs/jsptags.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- jsptags.html 2001/07/09 02:55:37 1.1 +++ jsptags.html 2001/10/22 03:43:56 1.2 @@ -149,7 +149,10 @@ <br> - <H4>Errors Tag</H4> + <H4>Errors Tag + + <i><font size="-1">(deprecated - see html:messages in Struts Tag Library)</font></i> + </H4> <p> This should have all the functionality of the Struts html:errors tag, but it iterates through the errors instead. @@ -166,7 +169,10 @@ <br> - <H4>Errors Exist Tag</H4> + <H4>Errors Exist Tag + + <i><font size="-1">(deprecated - see logic:messagesPresent in Struts Tag Library)</font></i> + </H4> <p> A simple logic tag that checks for an object in the request attribute under the default or specified error key. If there is an object, then the body of the tag is evaluated. @@ -193,7 +199,10 @@ <br> - <H4>Messages Tag</H4> + <H4>Messages Tag + + <i><font size="-1">(deprecated - see html:messages in Struts Tag Library)</font></i> + </H4> <p> This is similiar to the errors tag, but it is just for general messages. For instance you may want to send a general message that a certain number of records have been deleted, but you don't want it to come up under the @@ -209,7 +218,10 @@ <br> - <H4>Messages Exist Tag</H4> + <H4>Messages Exist Tag + + <i><font size="-1">(deprecated - see logic:messagesPresent in Struts Tag Library)</font></i> + </H4> <p> A simple logic tag that checks for an object in the request attribute under the default or specified message key. If there is an object, then the body of the tag is evaluated. 1.2 +3 -0 jakarta-struts/contrib/validator/docs/installation.html Index: installation.html =================================================================== RCS file: /home/cvs/jakarta-struts/contrib/validator/docs/installation.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- installation.html 2001/07/09 02:55:37 1.1 +++ installation.html 2001/10/22 03:43:56 1.2 @@ -83,6 +83,9 @@ <p>Copy the validators that you want to use from the validation.xml file in /web/example/WEB-INF or make your own. </p> + <p>Then extend com.wintecinc.struts.action.ValidatorForm instead of + org.apache.struts.action.ActionForm. + </p> </td> <!-- / Body --> </tr>