You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@turbine.apache.org by tv...@apache.org on 2008/07/15 17:00:49 UTC
svn commit: r676934 - /turbine/fulcrum/trunk/intake/xdocs/howto.xml
Author: tv
Date: Tue Jul 15 08:00:48 2008
New Revision: 676934
URL: http://svn.apache.org/viewvc?rev=676934&view=rev
Log:
Updated documentation.
Modified:
turbine/fulcrum/trunk/intake/xdocs/howto.xml
Modified: turbine/fulcrum/trunk/intake/xdocs/howto.xml
URL: http://svn.apache.org/viewvc/turbine/fulcrum/trunk/intake/xdocs/howto.xml?rev=676934&r1=676933&r2=676934&view=diff
==============================================================================
--- turbine/fulcrum/trunk/intake/xdocs/howto.xml (original)
+++ turbine/fulcrum/trunk/intake/xdocs/howto.xml Tue Jul 15 08:00:48 2008
@@ -37,10 +37,10 @@
will allow a web application to take web form input, validate it and
then map the data to an object. Tools like the <a
href="http://db.apache.org/torque/">Torque</a> help provide mapping of Objects to the
-database and Intake helps map web form data to Objects. Intake can be used
+database and Intake helps map web form data to Objects. Intake can be used
standalone by any application that supports Avalon components. However it
has extensive integration with the <a href="http://turbine.apache.org/">Turbine</a>
-application server. This howto focuses on using it with Turbine.
+application framework. This HowTo focuses on using it with Turbine.
</p>
<p>
@@ -54,9 +54,9 @@
------------------
Intake
------------------
- Business Objects <- Torque Generated
+ Business Objects <- e.g. Torque Generated
------------------
- Peers <- Torque Generated
+ Peers <- e.g. Torque Generated
------------------
RDBMS
------------------
@@ -70,9 +70,10 @@
regular expression matching in order to make sure that form fields
contain the data that they should contain. For example, if someone
should only enter a number into a form field, it can be validated with a
-regular expression. Lastly, Intake can provides a centralized source for
-error messages. If the validation fails, the error message defined in
-the XML file can be shown to the user.
+regular expression. Intake also supports the input of localized values and
+does the right thing based on the Locale the user requested. Lastly, Intake can
+provide a centralized source for error messages. If the validation fails, the
+error message defined in the XML file can be shown to the user.
</p>
</section>
@@ -83,23 +84,19 @@
First, here is the role configuration.
</p>
-<source>
-<![CDATA[
+<source><![CDATA[
<role
name="org.apache.fulcrum.intake.IntakeService"
shorthand="intake"
default-class="org.apache.fulcrum.intake.IntakeServiceImpl"/>
-]]>
-</source>
+]]></source>
<p>
Now comes the basic configuration of the component. Here will will
configure the various bundles.
</p>
-<source>
-
-<![CDATA[
+<source><![CDATA[
<intake>
<serialDataPath>./target/appData.ser</serialDataPath>
<xmlPaths>
@@ -107,15 +104,14 @@
<xmlPath>src/test/xmlConf2.xml</xmlPath>
</xmlPaths>
</intake>
-]]>
-</source>
+]]></source>
</section>
<section name="Usage">
<p>
-Intake is implemented as a Avalon component. Access to it is provided by
-a Turbine Pull Tool. An XML specification is parsed during the service
+Intake is implemented as a Avalon component. Access to it is provided by
+a Turbine Pull Tool. One or more XML specifications are parsed during the service
initialization and used by the pull tool while processing request data
and generating the response.
</p>
@@ -142,7 +138,7 @@
<section name="Xml File">
<p>
-The following example come from <a
+The following example comes from <a
href="http://scarab.tigris.org/">Scarab</a>. These are a couple of
groups from Scarab's intake.xml:
</p>
@@ -154,20 +150,20 @@
mapToObject="om.AttributeValue">
<field name="Value" key="val" type="String">
<rule name="maxLength" value="255">Value length cannot be > 255</rule>
- <required-message>This module requires data for this
- attribute.
- </required-message>
+ <rule name="required" value="true">This module requires data for
+ this attribute.
+ </rule>
</field>
<field name="Url" key="url" type="String" mapToProperty="Value">
<rule name="maxLength" value="255">Url length cannot be > 255</rule>
<rule name="mask" value="^$|http.+">Please enter an url starting with "http"</rule>
- <required-message>This module requires a valid url.</required-message>
+ <rule name="required" value="true">This module requires a valid url.</rule>
</field>
<field name="OptionId" key="optionid" type="NumberKey">
<rule name="mask" value="^$|[0-9]+">Please select a valid choice</rule>
- <required-message>This module requires that you select an option
- for this attribute.
- </required-message>
+ <rule name="required" value="true">This module requires that you select
+ an option for this attribute.
+ </rule>
</field>
</group>
@@ -194,9 +190,9 @@
</p>
<p>
-The group tag has a class attribute which is the name that will be used
+The group tag has a <code>name</code> attribute which is the name that will be used
within templates and java code to refer to the group. It also contains a
-key attribute which will be used in the query parameters. The key is
+<code>key</code> attribute which will be used in the query parameters. The key is
not referenced in any code, so it can be a short name (even 1 character) as
long as it is uniquely identifies the group from the rest.
</p>
@@ -206,14 +202,34 @@
objects.
</p>
<p>
-Fields have attributes: name and key which serve similar function to the
-group's class and key attributes. It has mapToObject and mapToProperty fields
+Fields have attributes: <code>name</code> and <code>key</code> which serve
+similar function to the group's <code>name</code> and <code>key</code>
+attributes. It has <code>mapToObject</code> and <code>mapToProperty</code> fields
that can be used to associate a business object to the field for prepopulating
the field as well as assigning the field data to the bean after successful
-validation. The field must have a type, which can be simple types such as
-String and Integer. It is planned that more complex types, such as
-Email, Url, or Date, will be added that will add functionality that is
-difficult or not possible with a simple regex mask.
+validation. The field must have a <code>type</code> out of the following
+supported types:
+<ul>
+ <li><code>boolean</code></li>
+ <li><code>BigDecimal</code> This field type supports localization.</li>
+ <li><code>int</code></li>
+ <li><code>float</code> This field type supports localization.</li>
+ <li><code>FileItem</code></li>
+ <li><code>String</code> (default)</li>
+ <li><code>DateString</code></li>
+ <li><code>double</code> This field type supports localization.</li>
+ <li><code>short</code></li>
+ <li><code>long</code></li>
+ <li><code>custom</code> Custom field types can be defined by using this type.
+ The class name of the customized field must be given in the <code>fieldClass</code>
+ attribute then. The custom class must extend the class
+ <code>org.apache.fulcrum.intake.model.Field</code>. This way, more
+ complex types, such as Email, Url, or Date, can be added that add functionality
+ that is difficult or not possible with a simple regex mask.</li>
+</ul>
+The field types supporting localization will parse the given strings from the
+request using the locale from the parser to allow the entry of floating point numbers with
+localized decimal separators.
</p>
<p>
The field can define rule elements. The basic fields include rules for
@@ -520,14 +536,14 @@
<source><![CDATA[
<field name="Value" key="val" type="String">
<rule name="maxLength" value="255">Value length cannot be > 255</rule>
- <required-message>This module requires data for this
- attribute.
- </required-message>
+ <rule name="required" value="true">This module requires data for
+ this attribute.
+ </rule>
</field>
<field name="Url" key="url" type="String" mapToProperty="Value">
<rule name="maxLength" value="255">Url length cannot be > 255</rule>
<rule name="mask" value="^$|http.+">Please enter an url starting with "http"</rule>
- <required-message>This module requires a valid url.</required-message>
+ <rule name="required" value="true">This module requires a valid url.</rule>
</field>
]]></source>
@@ -637,26 +653,26 @@
</p>
<source><![CDATA[
- <field name="Value" key="val" type="String">
- <rule name="maxLength" value="255">Value length cannot be > 255</rule>
- <required-message>This module requires data for this
- attribute.
- </required-message>
- </field>
- <field name="Url" key="url" type="String" mapToProperty="Value">
- <rule name="maxLength" value="255">Url length cannot be > 255</rule>
- <rule name="mask" value="^$|http.+">Please enter an url starting with "http"</rule>
- <required-message>This module requires a valid url.</required-message>
- </field>
+<field name="Value" key="val" type="String">
+ <rule name="maxLength" value="255">Value length cannot be > 255</rule>
+ <rule name="required" value="true">This module requires data for
+ this attribute.
+ </rule>
+</field>
+<field name="Url" key="url" type="String" mapToProperty="Value">
+ <rule name="maxLength" value="255">Url length cannot be > 255</rule>
+ <rule name="mask" value="^$|http.+">Please enter an url starting with "http"</rule>
+ <rule name="required" value="true">This module requires a valid url.</rule>
+</field>
]]></source>
- </section>
+</section>
- <section name="Multiple groups of the same class in one form">
+<section name="Multiple groups of the same class in one form">
<p>
This example uses a form from Scarab that assigns values to various
-attribute's that are relevant for an issue (bug). Attributes include
+attribute's that are relevant for an issue (bug). Attributes include
summary, operating system, platform, assigned to, etc. Some of the
attributes are required, but not all.
</p>
@@ -672,7 +688,6 @@
#set ($module = $user.CurrentModule)
#set ($issue = $user.ReportingIssue)
-
<form method="get" action="$action">
<hr><br>Please fill in the following:<br><br>
@@ -702,28 +717,24 @@
<br>
#attrValueSelect ($attVal $field "")
#else
-
<font color="red">
#attrValueErrorMsg ( $attVal $field )
</font>
<br>
#if ($attVal.Attribute.AttributeType.Name == "long-string" )
-
- <textarea name= "$attrInput.Value.Key" cols="40"
+ <textarea name= "$attrInput.Value.Key" cols="40"
rows="5">$!attrInput.Value</textarea>
#else
-
<input name= "$attrInput.Value.Key"
value="$!attrInput.Value" size="20" type="text">
-
#end
<br><br>
#end
#end
<p>
- <input type="submit"
- name="eventSubmit_doEnterissue" value="Submit Issue">
+ <input type="submit"
+ name="eventSubmit_doEnterissue" value="Submit Issue">
$intake.declareGroups()
</form>
@@ -875,13 +886,13 @@
john mcnally
]]></source>
- </section>
+</section>
- <section name="Default Values for fields">
+<section name="Default values for fields">
<p>
-If you want to use input fields which should default to non-empty values,
-you can use the defaultValue field:
+If you want to use input fields which should default to non-empty values for,
+new objects, you can use the defaultValue field:
</p>
<source><![CDATA[
@@ -891,7 +902,7 @@
</group>
]]></source>
-If you set up a form like this:
+<p>If you set up a form like this:</p>
<source><![CDATA[
#if($!dz)
@@ -913,6 +924,151 @@
</section>
- </body>
+<section name="Empty fields">
+<p>
+Sometimes you have form fields which are not required (can be left
+empty) but should be mapped onto a non null value in your bean. This
+is especially true if you use string fields in conjunction with
+"required" columns in a database. For this case, you can preset an
+"empty" value for each field which is used if a field is missing or
+empty in the form parameters returned by the browser. If you don't set
+this, the default is "null".
+</p>
+
+<source><![CDATA[
+<group name="test" key="test">
+ <field name="Value" key="val" type="String" emptyValue=""/>
+</group>
+]]></source>
+
+<p>This would return the empty String (not a null value) for the "val" field
+if the user does not enter anything. Without the emptyValue parameter, intake
+would assign the null value to the bean field.</p>
+
+</section>
+
+<section name="Display attributes for fields">
+<p>
+The Intake DTD allows additional attributes that can help you in your
+template. The <code>displayName</code> can be used to provide a label
+for the given field. The <code>displaySize</code> can be used to define
+the displayed size of the field (either numerical or as a CSS-style).
+The Intake tool $intake provides these values as
+<code>$field.DisplayName</code> and <code>$field.DisplaySize</code>,
+respectively.
+</p>
+
+<source><![CDATA[
+<group name="test" key="test">
+ <field name="Value" key="val" type="String"
+ displayName="Test Value"
+ displaySize="150px"
+ />
+</group>
+]]></source>
+
+<p>This could be used in the template like this:</p>
+
+<source><![CDATA[
+#set ($tg = $intake.test.Default)
+
+$tg.Value.DisplayName:
+<input type="text" name="$tg.Value.Key" value="$!tg.Value.HTMLString"
+ style="width:${tg.Value.DisplaySize};" />
+]]></source>
+
+</section>
+
+<section name="Custom validators">
+<p>
+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>
+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>
</document>