[jboss-cvs] jboss-seam/doc/reference/en/modules ...

[Shane Bryzak]

  User: sbryzak2
  Date: 07/02/08 05:28:39

  Modified:    doc/reference/en/modules  security.xml
  Log:
  Captcha documentation
  
  Revision  Changes    Path
  1.24      +69 -0     jboss-seam/doc/reference/en/modules/security.xml
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: security.xml
  ===================================================================
  RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/security.xml,v
  retrieving revision 1.23
  retrieving revision 1.24
  diff -u -b -r1.23 -r1.24
  --- security.xml	8 Feb 2007 02:53:15 -0000	1.23
  +++ security.xml	8 Feb 2007 10:28:39 -0000	1.24
  @@ -748,4 +748,73 @@
       
     </sect1>
   
  +  <sect1>
  +    <title>Implementing a Captcha Test</title>
  +    
  +    <para>
  +      Though strictly not part of the security API, it might be useful in certain circumstances (such as new
  +      user registrations, posting to a public blog or forum) to implement a Captcha (<emphasis>C</emphasis>ompletely 
  +      <emphasis>A</emphasis>utomated <emphasis>P</emphasis>ublic <emphasis>T</emphasis>uring test to tell 
  +      <emphasis>C</emphasis>omputers and <emphasis>H</emphasis>umans <emphasis>A</emphasis>part) to 
  +      prevent automated bots from interacting with your application.  Seam provides seamless integration with
  +      JCaptcha, an excellent library for generating Captcha challenges.  If you wish to use the captcha
  +      feature in your application you need to include the jcaptcha-* jar file from the Seam lib directory in your project.
  +    </para>
  +    
  +    <sect2>
  +      <title>Configuring the Captcha Servlet</title>
  +      <para>
  +        To get up and running, it is necessary to configure the Captcha Servlet, a servlet that will provide
  +        Captcha images to your pages.  This requires the following entry in <literal>web.xml</literal>:
  +      </para>
  +      
  +      <programlisting>
  +        <![CDATA[
  +    <servlet>
  +      <servlet-name>Captcha Servlet</servlet-name>
  +      <servlet-class>org.jboss.seam.servlet.CaptchaServlet</servlet-class>
  +    </servlet>
  +    
  +    <servlet-mapping>
  +      <servlet-name>Captcha Servlet</servlet-name>
  +      <url-pattern>/captcha</url-pattern>
  +    </servlet-mapping>        
  +        ]]>
  +      </programlisting>
  +      
  +    </sect2>
  +    
  +    <sect2>
  +      <title>Adding a Captcha to a page</title>
  +      
  +      <para>
  +        Adding a captcha challenge to a page is extremely easy.  Seam provides a page-scoped component,
  +        <literal>captcha</literal>, which provides everything that is required, including built-in captcha
  +        validation.  Here's an example:
  +      </para>
  +      
  +      <programlisting>
  +        <![CDATA[
  +  <div>
  +    <h:graphicImage value="/captcha?#{captcha.id}"/>
  +  </div>
  +  
  +  <div>
  +    <h:outputLabel for="verifyCaptcha">Enter the above letters</h:outputLabel>
  +    <h:inputText id="verifyCaptcha" value="#{captcha.response}" required="true"/>
  +    <div class="validationError"><h:message for="verifyCaptcha"/></div>
  +  </div>        
  +        ]]>
  +      </programlisting>
  +      
  +      <para>
  +        That's all there is to it.  The <literal>graphicImage</literal> control displays the Captcha challenge,
  +        and the <literal>inputText</literal> receives the user's response.  The response is automatically 
  +        validated against the Captcha when the form is submitted.
  +      </para>
  +      
  +    </sect2>
  +    
  +  </sect1>
  +
   </chapter>