svn commit: r225665 - /struts/core/trunk/doc/shale/features.xml

[dg...@apache.org]

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>
+&lt;%@ taglib uri="http://struts.apache.org/shale/core" prefix="s" %&gt;
+...
+&lt;h:form onsubmit="validateForm(this)"&gt;
+
+    &lt;h:inputText id="creditCardNumber" 
+                      size="16"
+                   value="#{userContext.creditCardNumber}"&gt;
+
+        &lt;s:commonsValidator type="required"
+                                                 arg="#{msgs.creditCardNumberPrompt}"
+                                           server="true"
+                                            client="true"/&gt;
+
+        &lt;s:commonsValidator type="mask"
+                                             mask="[4-6].*"
+                                                 arg="#{msgs.creditCardNumberPrompt}"
+                                           server="true"
+                                            client="true"/&gt;
+
+        &lt;s:commonsValidator type="creditCard" 
+	                                         arg="#{msgs.creditCardNumberPrompt}" 
+                                           server="true"&gt;
+    &lt;/h:inputText&gt; 
+
+    &lt;h:message for="creditCardNumber" styleClass="errors"/&gt; 
+
+    &lt;s:validatorScript functionName="validateForm"/&gt;
+&lt;/form&gt;
+...
+</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: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org