Author: msorokin
Date: 2009-05-06 10:46:51 -0400 (Wed, 06 May 2009)
New Revision: 14037
Added:
trunk/docs/realworld_app_guide/en/src/main/docbook/includes/validators.xml
Log:
added VUser Input Data Validation chapter
https://jira.jboss.org/jira/browse/RF-5768
Added: trunk/docs/realworld_app_guide/en/src/main/docbook/includes/validators.xml
===================================================================
--- trunk/docs/realworld_app_guide/en/src/main/docbook/includes/validators.xml
(rev 0)
+++ trunk/docs/realworld_app_guide/en/src/main/docbook/includes/validators.xml 2009-05-06
14:46:51 UTC (rev 14037)
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="Validators">
+ <title>User Input Data Validation</title>
+ <para>
+ Validation of user input is a very frequent situation for a developer. RichFaces
library offers 3 component to get this job done:
+ <emphasis
role="bold"><property><rich:beanValidator/></property></emphasis>,
<emphasis
role="bold"><property><rich:graphValidator/></property></emphasis>,
+
+ and <emphasis
role="bold"><property><rich:ajaxValidator/></property></emphasis>.
The latter two components are used in the Photo Album application. <emphasis
role="bold"><property><rich:graphValidator/></property></emphasis>
is intended to validate the whole object or the graph of interrelated objects and the
validation occurs when the whole form is submitted. While <emphasis
role="bold"><property><rich:ajaxValidator/></property></emphasis>
validates only one input field or a value at a time, validation is activated upon some
event and adds interactivity to the application.
+ Both components use Hibernate validators which helps to locate validation logic in
one place, such approach is really helpful given that usually data validation logic is
stored in multiple places including UI pages and in Java code that interacts with a
database.
+ </para>
+ <para>
+
+ Let's have a look at the components usage on the registration page. This is
how the page looks like (some irrelevant details were removed from the example):
+
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<ui:composition
xmlns="http://www.w3.org/1999/xhtml" ...
+
+ <rich:graphValidator>
+ ...
+ <h:inputText id="loginName" value="#{user.login}" />
+ <rich:messages for="loginName" />
+ <h:inputSecret required="true" id="password"
value="#{user.password}" />
+ <rich:messages for="password" />
+ <h:inputSecret required="true" id="confirmPassword"
+ value="#{user.confirmPassword}" />
+ <rich:messages for="confirmPassword" />
+ <h:inputText id="firstname" value="#{user.firstName}" />
+ <rich:messages for="firstname" style="color:red;" />
+ <h:inputText id="secondname" value="#{user.secondName}" />
+ <rich:messages for="secondname" />
+ <h:selectOneRadio required="true" id="sex"
value="#{user.sex}">
+ <f:selectItems value="#{userPrefsBean.sexs}" />
+ <s:convertEnum />
+ </h:selectOneRadio>
+ <rich:messages for="sex" />
+ <a4j:outputPanel id="calendar" layout="block">
+ <rich:calendar id="birthDate" value="#{user.birthDate}"
+
+ <rich:ajaxValidator event="oninputblur" />
+ </rich:calendar>
+ </a4j:outputPanel>
+ <rich:messages for="birthDate" />
+ <h:inputText id="email" value="#{user.email}" />
+ <rich:messages for="email" />
+ </rich:graphValidator>
+ <richx:commandButton actionListener="#{authenticator.register(user)}"
+ value="Register" />
+ <richx:commandButton actionListener="#{controller.cancelRegistration()}"
+ immediate="true" value="Cancel" />
+</ui:composition>
+
+...]]></programlisting>
+
+ <para>
+
+ <emphasis
role="bold"><property><rich:graphValidator/></property></emphasis>
validates the entity User object, in which restrictions are set with the help of
Hibernate annotations.
+ When the <emphasis role="bold" >Register</emphasis>
button is clicked on the <property>name, password, sex</property> etc. fields
are validated sequentially. In case of an error (for example, if a
<property>loginName</property> contains only on character and the annotation
restricts it to at least 3 characters to be typed in) a error message in red color is
displayed next to the input field and the request is aborted. If all values are valid
the <code>authenticator.register(user)</code> method will be invoked and the
user will be saved to the database.
+
+ </para>
+ <para>
+ <emphasis
role="bold"><property><rich:ajaxValidator/></property></emphasis>
acts in a slightly different way, in our case it is attached to the
<code>user.birthDate</code> field. When the value of the field is changed and
the field loses focus it is immediately validated. If the input data is incorrect and
error message will displayed, which is a quick way to respond to user input errors and
avoid sending incorrect data to the server.
+
+ </para>
+ <para>
+ If you would like to get more details about the validators that RichFaces library
provides please visit <link
url="http://livedemo.exadel.com/richfaces-demo/richfaces/ajaxValidat...
Demo</link> web page and <link
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...
>RichFaces Developer Guide</link>.
+
+ </para>
+</section>