Author: husted
Date: Thu Nov 4 06:39:48 2004
New Revision: 56595
Modified:
struts/trunk/doc/userGuide/dev_validator.xml
Log:
Clarify which Validator configuration file is which, and why there is more than one.
When refering to an object loaded by the validator element, prefer the term
"validator" to "rule" or "action".
Modified: struts/trunk/doc/userGuide/dev_validator.xml
==============================================================================
--- struts/trunk/doc/userGuide/dev_validator.xml (original)
+++ struts/trunk/doc/userGuide/dev_validator.xml Thu Nov 4 06:39:48 2004
@@ -40,25 +40,26 @@
<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
+ attribute from the Struts Configuration 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>
+ The form element's <code>name</code> attribute in the
+ Validator configuration should match the 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.
+ An alternative approach is to use the action mapping path attribute.
+ In this case, you extend 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.
+ attribute from the Struts configuration which should match the form element's
+ <code>name</code> attribute in the Validator configuration.
</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.
+ Then a separate action mapping can be defined for each page in a multi-page
+ form, and the validation form can be associated with the action rather than
+ a page number (as shown in the example of a multi-page form in the validator
+ example).
</p>
</section>
@@ -66,12 +67,12 @@
<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.
+ Each validator form is grouped within a <code>FormSet</code> element in
+ the Validator configuration 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.
+ If these attributes are not specified, 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
@@ -158,7 +159,7 @@
<section href="builtin" name="Standard Built In Validations">
<p>
- Validator is shipped with the following set of pre-defined validation rules.
+ Validator ships with a set of pre-defined validators, as follows:
</p>
<ul>
<li><strong>required</strong> - mandatory field validation. Has no
variables.
@@ -249,7 +250,7 @@
]]></code></pre>
</li>
<li><strong>date</strong> - validates that a field can be converted to
a Date.
- This validation rule uses <code>java.text.SimpleDateFormat</code>
to parse the date and
+ This validator uses <code>java.text.SimpleDateFormat</code> to
parse the date and
optionally either a <code>datePattern</code> or
<code>datePatternStrict</code> variable can be used.
If no pattern is specified the default short date format is
assumed. The difference
between using the <code>datePatternStrict</code> and
<code>datePattern</code> variables
@@ -440,9 +441,9 @@
a password twice for confirmation, to make sure that the values match.)
In addition, there are fields in a form that may only be required if
other fields have certain values. The <code>validwhen</code>
- validation rule is designed to handle these cases.</p>
+ validator is designed to handle these cases.</p>
<p>
- The <code>validwhen</code> rule takes a single <code>var</code> field,
+ The <code>validwhen</code> validator takes a single <code>var</code> field,
called <code>test</code>. The value of this var is a boolean expression
which must be true in order for the validation to success. The
values which are allowed in the expression are:</p>
@@ -470,7 +471,7 @@
fields <code>sendNewsletter</code> and <code>emailAddress</code>.
The <code>emailAddress</code> field is only required if the
<code>sendNewsletter</code> field is not null. You could code
- this using the validwhen rule as:</p>
+ this using validwhen as:</p>
<pre><code><![CDATA[
<field property="emailAddress" depends="validwhen">
<arg0 key="userinfo.emailAddress.label"/>
@@ -530,19 +531,27 @@
<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,
+ By convention, the validators your application uses can beloaded through a
+ file named "validator-rules.xml", and the validator forms (or "validations")
+ can be configured separately (say, in a "validations.xml" file). This
+ approach separates the validators, that you might reuse in another
+ application, from the validations that are specific to each application.
+ </p>
+
+ <p>
+ The Validator comes bundled with several ready-to-use validators. The
+ bundled validators include: 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
+ The 'mask' validator depends on 'required' in the default setup.
+ That means that 'required' has to complete successfully 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.
+ The 'required' and 'mask' validators are partially built into the framework.
+ Any field that isn't 'required' will skip other validations if the field is null
+ or has a length of zero. Regardless, the implementations of 'required' and 'mask'
+ are still plugged in through the configuration file, like all the others.
</p>
<p>
@@ -554,16 +563,17 @@
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.
+ The 'mask' validator lets you validate a regular expression mask to the field.
It uses the Regular Expression Package from the Apache Jakarta site.
- All validation rules can be stored in the validator-rules.xml file.
+ </p>
+
+ <p>
The main class used is <code>org.apache.regexp.RE</code>.
</p>
<p>
- Example Validator Configuration from validation.xml.
+ Example Validator Configuration from the default validator-rules.xml.
</p>
<pre><code><![CDATA[
@@ -763,17 +773,17 @@
<p>
You can define logic like "only validate this field if field X is
non-null and field Y equals 'male'". The recommended way to do this will
- be with the <code>validwhen</code> rule, described above, and available
+ be with the <code>validwhen</code> validator, described above, and available
since Struts 1.2.0. The
- <code>requiredif</code> validation rule, which was added since Struts 1.1,
- will be deprecated in favor of this rule, and will be removed in a
- future release. However, if you are using <code>requiredif</code>, here
- is a brief tutorial.
+ <code>requiredif</code> validator, which was added since Struts 1.1,
+ will be deprecated in favor of <code>validwhen</code>, and
+ <code>requiredif</code> will be removed in a future release. However, if you
+ are using <code>requiredif</code>, here is a brief tutorial.
</p>
<p>Let's assume you have a medical information form with three fields, sex,
pregnancyTest, and testResult.
If sex is 'f' or 'F', pregnancyTest is required. If pregnancyTest is not blank,
testResult is required.
- The entry in your validation.xml file would look like this:
+ The entry in your Validator configuration would look like this:
</p>
<pre>
<![CDATA[
@@ -832,7 +842,7 @@
</p>
<p>
- If you have this in your struts-config.xml
+ If you have this in your Struts configuration
</p>
<pre><![CDATA[
@@ -969,8 +979,8 @@
</p>
<p>
- Here's a sample configuration block that you could use in the
- struts-config.xml:
+ Here's a sample configuration block that you could use in your
+ Struts configuration file:
</p>
<pre>
@@ -978,7 +988,7 @@
<![CDATA[
<plug-in className="org.apache.struts.validator.ValidatorPlugIn">
<set-property property="pathnames"
- value="/WEB-INF/validation.xml,/WEB-INF/validator-rules.xml"/>
+ value="/WEB-INF/validator-rules.xml,/WEB-INF/validations.xml"/>
<set-property property="stopOnFirstError" value="false"/>
</plug-in>
]]>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
