Author: dgeary
Date: Wed Jul 27 18:48:47 2005
New Revision: 225665
URL: http://svn.apache.org/viewcvs?rev=225665&view=rev
Log:
Added validation documentation. I'll add Tiles documentation soon.
Modified:
struts/core/trunk/doc/shale/features.xml
Modified: struts/core/trunk/doc/shale/features.xml
URL:
http://svn.apache.org/viewcvs/struts/core/trunk/doc/shale/features.xml?rev=225665&r1=225664&r2=225665&view=diff
==============================================================================
--- struts/core/trunk/doc/shale/features.xml (original)
+++ struts/core/trunk/doc/shale/features.xml Wed Jul 27 18:48:47 2005
@@ -403,12 +403,108 @@
</section>
- <section name="Shale Validation" href="validation">
+ <section name="Commons Validator Integration" href="validation">
- <p>FIXME - Describe validation feature.</p>
+ <subsection name="Validation Introduction"
href="validation-introduction">
- </section>
+ <p>JavaServer Faces 1.x does not explicitly support client-side
+ validation and only provides a minimal set of server-side
+ validators. On the other hand, <a
href="http://jakarta.apache.org/commons/validator/";>Apache Commons Validator</a>
+ supports both client- and server-side validators and comes
+ with the following useful validators:</p>
+ <ul>
+ <li>Credit Card</li>
+ <li>Date</li>
+ <li>Email</li>
+ <li>Generic</li>
+ <li>ISBN</li>
+ <li>URL</li>
+ </ul>
+
+ <p>All of the preceeding validators can be executed either on
+ the client or the server, or both. Shale integrates
JavaServer Faces
+ and the Commons Validator.</p>
+
+ </subsection>
+
+ <subsection name="Services Provided" href="validation-services">
+
+ <p>Shale provides two JSP tags that let you use the Commons Validator:
+ <code>s:commonsValidator</code> and
<code>s:validatorScript</code>. The
+ former lets you attach a commons validator to a JSF input
component and
+ the latter generates JavaScript validation code for
validating each JSF component
+ that has one or more Commons validators in a particular form.
You can attach as
+ many Commons validators to a single JSF input component as
you wish.</p>
+
+ </subsection>
+
+ <subsection name="Using Commons Validator Integration"
href="validation-using">
+
+ <p>Here's what you need to do to use Shale validation:</p>
+ <ul>
+ <li>Add <code>validator-rules.xml</code>, from the
Commons Validator distribution,
+ to your <code>WEB-INF</code> directory. (You can
find a copy of <code>validator-rules.xml</code>
+ in the Shale use-cases example. See
<code>.../shale/use-cases/src/web/WEB-INF/validator-rules.xml</code>)
+ </li>
+ <li>
+ Add an <code>onsubmit</code> attribute to your
<code>h:form</code> tag that calls
+ the JavaScript validation function generated
by <code>s:validatorScript</code>.
+ </li>
+ <li>
+ Add Commons validators to JSF input components with
<code>s:commonsValidator</code>
+ </li>
+ <li>
+ Add an <code>s:validatorScript</code> tag at the
end of the <code>h:form</code> tag's body.
+ </li>
+ </ul>
+
+ <p>Here's an example:</p>
+<pre>
+<%@ taglib uri="http://struts.apache.org/shale/core"; prefix="s" %>
+...
+<h:form onsubmit="validateForm(this)">
+
+ <h:inputText id="creditCardNumber"
+ size="16"
+ value="#{userContext.creditCardNumber}">
+
+ <s:commonsValidator type="required"
+
arg="#{msgs.creditCardNumberPrompt}"
+ server="true"
+ client="true"/>
+
+ <s:commonsValidator type="mask"
+ mask="[4-6].*"
+
arg="#{msgs.creditCardNumberPrompt}"
+ server="true"
+ client="true"/>
+
+ <s:commonsValidator type="creditCard"
+
arg="#{msgs.creditCardNumberPrompt}"
+ server="true">
+ </h:inputText>
+
+ <h:message for="creditCardNumber" styleClass="errors"/>
+
+ <s:validatorScript functionName="validateForm"/>
+</form>
+...
+</pre>
+ <p>In the preceeding example, we've attached three Commons validators
to a single
+ JSF input component. To pass validation, the field must
have a value that
+ starts with a number between 4 and 6 inclusive and
that value must be a valid
+ credit card number as verified by the <a
href="http://en.wikipedia.org/wiki/Luhn_algorithm";>Luhn</a> algorithm. Two of
the
+ validations are performed on both client and server
and one is performed
+ on the server only.</p>
+ <p><strong>Note:</strong> <i>At the present time, you
have the option to forego
+ server-side validation, which is considered very bad
practice. Users can turn off
+ JavaScript, so you should always backup client-side
validation with server-side
+ validation. In the future, Shale may enforce
server-side validation if it's
+ not explicitly specified.</i></p>
+ </subsection>
+
+ </section>
<section name="Shale Remoting" href="remoting">
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
