You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by tv...@apache.org on 2007/05/20 21:45:20 UTC
svn commit: r539922 - in
/jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs:
howto/intake-howto.xml services/intake-service.xml
Author: tv
Date: Sun May 20 12:45:19 2007
New Revision: 539922
URL: http://svn.apache.org/viewvc?view=rev&rev=539922
Log:
Updated Intake documentation
Modified:
jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/howto/intake-howto.xml
jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/services/intake-service.xml
Modified: jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/howto/intake-howto.xml
URL: http://svn.apache.org/viewvc/jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/howto/intake-howto.xml?view=diff&rev=539922&r1=539921&r2=539922
==============================================================================
--- jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/howto/intake-howto.xml (original)
+++ jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/howto/intake-howto.xml Sun May 20 12:45:19 2007
@@ -21,25 +21,26 @@
<document>
<properties>
- <title>"Simple" Intake How-to for Turbine 2.1</title>
+ <title>"Simple" Intake How-to for Turbine 2.3.3</title>
<author email="dantest@yorku.ca">Daniel Kha</author>
<author email="seade@backstagetech.com.au">Scott Eade</author>
+ <author email="tv@apache.org">Thomas Vandahl</author>
</properties>
<body>
<section name="Introduction">
<p>
First of all I'd like to note that this document is based on my
- experience in using Intake for Turbine 2.1. I've tried to make
+ experience in using Intake for Turbine 2.3.3. I've tried to make
it as correct as possible but I don't guarantee anything. This
has been written as a guide for a new Intake user and assumes
- some familiarity with Turbine 2.1.
+ some familiarity with Turbine 2.3.3.
</p>
<p>
To use intake, the following steps are required:
<ol>
- <li>Create your turbine template with a form.</li>
+ <li>Create your Turbine template with a form.</li>
<li>Create the intake.xml file.</li>
<li>Create a business object to represent the intake group
we are working with (this is optional).</li>
@@ -50,11 +51,13 @@
<p>
Some additional information concerning removing Intake group
information from the request is included at the bottom of this
- document.
+ document. See the
+ <a href="../services/intake-service.html">Intake Service Documentation</a>
+ for additional in-depth information on the features of Intake.
</p>
</section>
- <section name="Step 1: Create your turbine template with a form">
+ <section name="Step 1: Create your Turbine template with a form">
<p>
The first thing to do is the create the form in your template
(e.g. a velocity template file, a .vm file). Just create the
@@ -174,7 +177,7 @@
</p>
<source><![CDATA[
<!DOCTYPE input-data SYSTEM
- "http://jakarta.apache.org/turbine/dtd/intake_2_3.dtd">
+ "http://jakarta.apache.org/turbine/dtd/intake_2_3_3.dtd">
<input-data basePackage="ca.yorku.devteam.inca.clients.skeleton.">
...group elements goes here...
</input-data>
@@ -248,8 +251,8 @@
<p>
For a complete list of valid attributes of the group
element, please see the
- <a href="../services/intake-service.html">
- intake-service document</a> on the Turbine web site.
+ <a href="../services/intake-service.html">Intake Service Documentation</a>
+ on the Turbine web site.
</p>
</subsection>
@@ -273,8 +276,7 @@
]]></source>
<p/>
<p>
- A field element can have the following attributes:
-
+ Important attributes of the field element are like the following:
<ul>
<li>"name" attribute
<ul>
@@ -303,9 +305,10 @@
<li>
required, the type of the field so that
intake will know what to expect. Valid
- types I know of are: String, Integer (I
- believe these map to the corresponding Java
- types). Please see the intake.dtd for the
+ types I know of are: String, Integer,
+ DateString, BigDecimal etc. Please see the
+ <a href="../services/intake-service.html">Intake Service Documentation</a>
+ or the DTD in intake.dtd for the
allowed values.
</li>
</ul>
@@ -329,29 +332,42 @@
<p>
For a complete list of valid attributes of the field
element, please see the
- <a href="../services/intake-service.html">
- intake-service document</a> on the Turbine web site.
+ <a href="../services/intake-service.html">Intake Service Documentation</a>
+ on the Turbine web site.
</p>
</subsection>
<subsection name="<rule> elements">
<p>
In each field element, you can have rules defined. The
- supported rule elements for Intake in Turbine 2.1 are:
+ supported rule elements for Intake depend on the validators used.
+ The standard validators provide the following rules:
</p>
<source><![CDATA[
+<!-- DefaultValidator -->
<rule name="required" value="true">Error message for required failed</rule>
<rule name="minLength" value="4">Error message for required min length failed</rule>
<rule name="maxLength" value="9">Error message for required max length failed</rule>
+
+<!-- StringValidator -->
<rule name="mask" value="^[0-9]+$">Error message for regular expression failed</rule>
-<rule name="notANumberMessage">Error message for Number fields when the entry is not a number</rule>
+<!-- BigDecimalValidator, DoubleValidator, FloatValidator, IntegerValidator, -->
+<!-- LongValidator, ShortValidator -->
+<rule name="invalidNumber">Error message when the entry is not a number</rule>
+<rule name="minValue" value="0">Error message for values less than minValue</rule>
+<rule name="maxValue" value="100">Error message for values greater than maxValue</rule>
+
+<!-- DateStringValidator -->
+<rule name="format" value="MM/dd/yyyy">Error message for invalid dates</rule>
+<rule name="format[1-9]" value="MM/dd/yyyy">Error message for invalid dates</rule>
]]></source>
<p/>
<p>
- For more info on the supported rules, please see the
- <a href="../services/intake-service.html">
- intake-service document</a> on the Turbine web site:
+ For more info on the supported rules and on additional rules
+ for comparing fields with each other, please see the
+ <a href="../services/intake-service.html">Intake Service Documentation</a>
+ on the Turbine web site.
</p>
</subsection>
</section>
@@ -373,8 +389,8 @@
was designed to work with a database so the methods
get/setQueryKey doesn't make much sense if your business object
isn't based on a database model. For my use, I just force the
- key to be "_0" which is the default key used by Intake (as of
- Turbine 2.1). You could, of course, implement it as a normal
+ key to be "_0" which is the default key used by Intake.
+ You could, of course, implement it as a normal
data field to allow the template to set the query key and then
in the Action to get the query key. But then you'll have to
keep track of the key you use in both the template file and
@@ -422,7 +438,8 @@
* Performs user login
*/
public void doLogin(RunData data, Context context)
- throws Exception {
+ throws Exception
+{
// Get intake group
IntakeTool intake =
(IntakeTool)context.get("intake");
@@ -439,11 +456,14 @@
// template to be the same one as the user was filling out. Otherwise
// the user will just see the next template. See the "important note"
// in step 1.
- if (!group.isAllValid()) {
+ if (!group.isAllValid())
+ {
Log.debug("Group elements INVALID");
setTemplate(data, "Login.vm");
return;
- } else {
+ }
+ else
+ {
// If all is validated then you can set the next template and/or
// continue processing...it's up to you. You can also use
// setPage() in the template file to set the next template to show
@@ -471,7 +491,8 @@
* Performs user login
*/
public void doLogin(RunData data, Context context)
- throws Exception {
+ throws Exception
+{
// Get intake group
IntakeTool intake =
(IntakeTool)context.get("intake");
@@ -484,11 +505,14 @@
// template to be the same one as the user was filling out. Otherwise
// the user will just see the next template. See the "important note"
// in step 1.
- if (!group.isAllValid()) {
+ if (!group.isAllValid())
+ {
Log.debug("Group elements INVALID");
setTemplate(data, "Login.vm");
return;
- } else {
+ }
+ else
+ {
// If all is validated then you can set the next template and/or
// continue processing...it's up to you. You can also use
// setPage() in the template file to set the next template to show
Modified: jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/services/intake-service.xml
URL: http://svn.apache.org/viewvc/jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/services/intake-service.xml?view=diff&rev=539922&r1=539921&r2=539922
==============================================================================
--- jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/services/intake-service.xml (original)
+++ jakarta/turbine/core/branches/TURBINE_2_3_BRANCH/xdocs/services/intake-service.xml Sun May 20 12:45:19 2007
@@ -983,14 +983,92 @@
<section name="Custom validators">
<p>
-todo
+Fields can have custom validators through the help of the
+<code>validator</code> attribute. If the validator class is not
+qualified (i.e. has no package) the package
+<code>org.apache.turbine.services.intake.validator</code> is
+assumed. Validator classes must implement the
+<code>org.apache.turbine.services.intake.validator.Validator</code>
+interface. If the validator needs initialization from the list
+of constraints (based on the <code>rule</code> elements in the
+definition file), it also must implement
+<code>org.apache.turbine.services.intake.validator.InitableByConstraintMap</code>.
+It is recommended to extend one of the existing validator classes
+which live in the <code>org.apache.turbine.services.intake.validator</code>
+package. In this validator class, override <code>assertValidity(String)</code>,
+don't forget to call <code>super.assertValidity(testValue)</code> and add
+your own checks to the validator.
</p>
+<p>
+For validator classes extending <code>DefaultValidator</code>
+the most important method to implement is <code>assertValidity()</code>.
+There are two signatures of this method. If you just need to compare
+the value entered to a list of database entries, for example, it
+is sufficient to implement <code>assertValidity(String)</code>. The
+default code handles multi-valued fields and other stuff for you. If
+you want to do advanced checks and comparisons, you need to implement
+<code>assertValidity(Field)</code>. Here you can check for locale,
+associated group and values of other fields in the same group. See
+the following section for examples.
+</p>
+
</section>
<section name="Validating dependent fields">
<p>
-todo
+Sometimes it is necessary to validate fields not only against a set of
+constant rules but also against the values of other fields in the same
+form or group. For these cases, Intake provides the helper class
+<code>FieldReference</code>. It provides additional rules to compare
+fields to other fields:
</p>
+<table>
+ <tr>
+ <th>Rule Name</th>
+ <th>Comparison</th>
+ <th>Rule Value</th>
+ </tr>
+ <tr>
+ <td>less-than</td>
+ <td align="center"><</td>
+ <td><name of other field></td>
+ </tr>
+ <tr>
+ <td>greater-than</td>
+ <td align="center">></td>
+ <td><name of other field></td>
+ </tr>
+ <tr>
+ <td>less-than-or-equal</td>
+ <td align="center"><=</td>
+ <td><name of other field></td>
+ </tr>
+ <tr>
+ <td>greater-than-or-equal</td>
+ <td align="center">>=</td>
+ <td><name of other field></td>
+ </tr>
+</table>
+<p>
+Two examples of implementations of these comparison rules are
+available as <code>DateRangeValidator</code> and
+<code>IntegerRangeValidator</code>. An example on how to use these
+is shown below.
+</p>
+<source><![CDATA[
+<group name="DateRange" key="dr">
+ <field name="DateFrom" key="dmin" type="DateString">
+ <rule value="MM/dd/yyyy" name="format">Invalid format</rule>
+ </field>
+ <field name="DateTo" key="dmax" type="DateString"
+ validator="DateRangeValidator">
+ <rule value="MM/dd/yyyy" name="format">Invalid format</rule>
+ <rule value="DateFrom" name="greater-than">
+ To-Date must be greater than From-Date</rule>
+ </field>
+</group>
+]]></source>
+
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-dev-help@jakarta.apache.org