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>
