Google Git
Sign in
apache / turbine-core.git / 4589899eff025b0ccf665835d56c982b4fe65424 / . / howto / intake-howto.html
blob: 9242c14f12671099076eef1c304c255924734ab7 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/intake-howto.xml at 17 Jun 2025
| Rendered using Apache Maven Fluido Skin 2.1.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
<title>&quot;Simple&quot; Intake How-to for Turbine 2.1 – Apache Turbine</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script src="../js/apache-maven-fluido-2.1.0.min.js"></script>
<link rel="icon" type="image/png" sizes="48x48" href="./images/favicon.ico">
<link rel="icon" type="image/png" sizes="48x48" href="../images/favicon.ico">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style>.github-fork-ribbon:before { background-color: orange; }</style>
</head>
<body>
<a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
<div class="container-fluid container-fluid-top">
<header>
<div id="banner">
<div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="../images/turbine-project-apache-separate.png" alt="Apache Turbine" /></a></h1></div></div>
<div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="../images/logo.gif" /></a></h1></div></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 01 Apr 2025<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 7.0</li>
<li class="pull-right"><span class="divider">|</span>
<a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li>
<li class="pull-right"><span class="divider">|</span>
<a href="https://turbine.apache.org/">Turbine</a></li>
<li class="pull-right"><a href="https://www.apache.org">Apache</a></li>
</ul>
</div>
</header>
<div class="row-fluid">
<header id="leftColumn" class="span2">
<nav class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">General Information</li>
<li><a href="../index.html">Overview</a></li>
<li><a href="../features.html">Features</a></li>
<li><a href="../fsd.html">Specification</a></li>
<li><a href="../getting-started.html">Getting Started</a></li>
<li><a href="../how-to-build.html">Howto Build Turbine</a></li>
<li><a href="../changes-report.html">Changes</a></li>
<li class="nav-header">Documentation</li>
<li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li>
<li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a>
<ul class="nav nav-list">
<li><a href="../howto/action-event-howto.html">Action Events Howto</a></li>
<li><a href="../howto/annotations.html">Annotations Howto</a></li>
<li><a href="../howto/configuration-howto.html">Configuration Howto</a></li>
<li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li>
<li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li>
<li class="active"><a>Intake Howto</a></li>
<li><a href="../howto/jsp-howto.html">JSP Howto</a></li>
<li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li>
<li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li>
<li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li>
<li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li>
<li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li>
<li><a href="../howto/python-howto.html">Python Howto</a></li>
<li><a href="../howto/security-howto.html">Security Howto</a></li>
<li><a href="../howto/services-howto.html">Services Howto</a></li>
<li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li>
<li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li>
<li><a href="../howto/context-howto.html">Velocity Context Howto</a></li>
<li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li>
<li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li>
</ul></li>
<li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li>
<li><a href="../apidocs/index.html">JavaDocs</a></li>
<li class="nav-header">Development</li>
<li><a href="../proposals.html">Proposals</a></li>
<li><a href="../how-to-help.html">How To Help</a></li>
<li><a href="../todo.html">Todo</a></li>
<li class="nav-header">Project Documentation</li>
<li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
<li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
<li class="nav-header">Apache</li>
<li><a href="https://www.apache.org/">Apache Website</a></li>
<li><a href="https://www.apache.org/licenses/">License</a></li>
<li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li><a href="https://www.apache.org/security/">Security</a></li>
</ul>
</nav>
<div class="well sidebar-nav">
<form id="search-form" action="https://www.google.com/search" method="get" >
<input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" />
<input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." />
</form>
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</header>
<main id="bodyColumn" class="span10">
<section><a id="Introduction"></a>
<h1>Introduction</h1>
<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
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.
</p>
<p>
To use intake, the following steps are required:
</p>
<ol style="list-style-type: decimal;">
<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>
<li>Create the Turbine Action to handle the form
submission.</li>
</ol>
<p>
Some additional information concerning removing Intake group
information from the request is included at the bottom of this
document.
</p>
</section>
<section><a id="Step_1.3A_Create_your_turbine_template_with_a_form"></a>
<h1>Step 1: Create your turbine template with a form</h1>
<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
skeleton structure and don't worry about the field names and
values yet. Note that field names will have to match the names
specified in the intake.xml file. Actually you can do the
opposite (name the fields here first and match them in the
intake.xml file) if you wish, but this guide will do it the
former way.
</p>
<p>
Now add the following lines above the code for your form and
modify it to match the group and field names in your intake.xml
file (perhaps you can come back to do this step after you've
done your intake.xml file). Here is an example in a Velocity
template for a &quot;login form&quot;:
</p>
<pre class="prettyprint"><code>
#set($loginGroup = $intake.LoginGroup.Default)
</code></pre>
<p></p>
<p>
What this does is to set a Velocity variable called $loginGroup
to a default group object specified by intake.xml. The $intake
variable is the Turbine Pull Tool instance (IntakeTool). The
&quot;LoginGroup&quot; is the name of the group as specified in the
intake.xml file (names must match, and this is not the group's
key attribute.). The &quot;Default&quot; part obtains a generic default
intake group object. Or in other words, this resolves to
IntakeTool.get(String groupName) with the groupName being
&quot;LoginGroup&quot;. Also, you can re-write the statement as
$intake.get(&quot;LoginGroup&quot;).getDefault() in your template.
</p>
<p>
Or if you would like to map the intake group to a business
object (for whatever purpose) then you can do this (read on
for more info on what is required to do this in intake.xml and
the corresponding Turbine Action class):
</p>
<pre class="prettyprint"><code>
#set($loginGroup = $intake.LoginGroup.mapTo($mytool.getInstanceLoginForm()))
</code></pre>
<p></p>
<p>
What this does is to set a Velocity variable called $loginGroup
to an instance of the LoginForm business object (and if the
returned object has values in its fields and appropriate
&quot;getter&quot; methods then this would prepopulate the intake group
with the values. A good usage example of this is when you
would like to prepopulate the form with values from the
database and want to use intake to validate the form). It
makes use of a custom tool placed into the Velocity context as
&quot;$mytool&quot; (you can make your own tool to instantiate an instance
of your business object similar to this example).
</p>
<p>
So, depending on the method you use above, the corresponding
Turbine Action code will need to &quot;cooperate&quot; accordingly.
We'll discuss this later in step 4.
</p>
<p>
Near the end of the form (before you close the &quot;form&quot; tag)
include the following line:
</p>
<pre class="prettyprint"><code>
$intake.declareGroups()
</code></pre>
<p></p>
<p>
What this does is to fill in hidden form fields into the form
for use by intake.
</p>
<p>
In order to use Turbine's Action event system, the submit buttons
must adhere to the naming specification defined by
<a href="http://turbine.apache.org/turbine-2/howto/action-event-howto.html" class="externalLink">
Turbine's Action event system</a>.
</p>
<section><a id="a.2A.2A.2A_IMPORTANT_NOTE_.2A.2A.2A"></a>
<h2>*** IMPORTANT NOTE ***</h2>
<p>
If you use
$link.setAction('SomeAction').setPage('NextTemplate.vm')
in your form's action attribute like this:
</p>
<pre class="prettyprint"><code>
&lt;form name=&quot;myForm&quot; method=&quot;POST&quot;
action=&quot;$link.setAction('LoginAction').setPage('NextTemplate.vm')&quot;&gt;
...
&lt;/form&gt;
</code></pre>
<p></p>
<p>
then the form validation won't appear to work (i.e. the user
will see the NextTemplate.vm file instead of the form they
were trying to fill out which failed validation). To work
around this problem, you can omit the setPage('...') part
in your form's action attribute and then have your action
route the user to the next template on validation success
OR somehow detect the current form the user is at and if
the validation fails, override the next template to the
current template (which is really just overriding the
setPage() part in the template file specified by the web
designer).
</p>
</section>
</section>
<section><a id="Step_2.3A_Create_the_intake.xml_file"></a>
<h1>Step 2: Create the intake.xml file</h1>
<p>
The intake.xml file specifies the validation rules required to
be satisfied in order for the form to be accepted. The file has
a &quot;root&quot; XML element of &quot;input-data&quot; and in that would be
&quot;group&quot; elements.
</p>
<p>
Here is an example of the element (with no other sub-elements):
</p>
<pre class="prettyprint"><code>
&lt;!DOCTYPE input-data SYSTEM
&quot;http://turbine.apache.org/dtd/intake_2_3.dtd&quot;&gt;
&lt;input-data basePackage=&quot;ca.yorku.devteam.inca.clients.skeleton.&quot;&gt;
...group elements goes here...
&lt;/input-data&gt;
</code></pre>
<p></p>
<p>
Notice the basePackage attribute (optional) points to the
skeleton package with an extra period at the end. This
attribute specifies the package that contains the java objects
the &quot;group&quot; and &quot;field&quot; elements can optionally map to.
The trailing period is REQUIRED.
</p>
<section><a id="a.3Cgroup.3E_elements"></a>
<h2>&lt;group&gt; elements</h2>
<p>
Each group element represents a collection of field information you'd like to
validate in your form. For example, on a login page you would have a form for
the user to input their username and password, and as well as a login button.
This entire form would be grouped as a group in the intake.xml file.
</p>
<p>
Here is an example of a group with no other elements (not useful yet):
</p>
<pre class="prettyprint"><code>
&lt;group name=&quot;LoginGroup&quot; key=&quot;loginGroupKey&quot; mapToObject=&quot;LoginForm&quot;&gt;
...field elements goes here...
&lt;/group&gt;
</code></pre>
<p></p>
<p>
A group element can have the following attributes:
</p>
<ul>
<li>&quot;name&quot; attribute
<ul>
<li>
the name of the group, is required, and must
be unique across the entire intake.xml file.
</li>
</ul>
</li>
</ul>
<ul>
<li>&quot;key&quot; attribute
<ul>
<li>
the key of the group, is required, and must
be unique across the entire intake.xml file.
</li>
</ul>
</li>
</ul>
<ul>
<li>&quot;mapToObject&quot; attribute
<ul>
<li>
optional, used if you want to map the form
to a business object. Note that the field
names specified later by the &quot;field&quot; element
in the group should match the field names of
the business object with appropriate get/set
methods. See the &quot;field&quot; tag examples to
find how to override this default behaviour.
</li>
</ul>
</li>
</ul>
<p>
For a complete list of valid attributes of the group
element, please see the
<a href="http://turbine.apache.org/turbine-2/services/intake-service.html" class="externalLink">
intake-service document</a> on the Turbine web site.
</p>
</section>
<section><a id="a.3Cfield.3E_elements"></a>
<h2>&lt;field&gt; elements</h2>
<p>
Each group element can contain any number of &quot;field&quot;
elements. Each field element will correspond to a field in
the form. The name and key of each field will be used in
the form code in the template so make sure the names and
keys match in both files (intake.xml and the template file).
</p>
<p>
Here is an example of a field with no other elements (not
too useful yet):
</p>
<pre class="prettyprint"><code>
&lt;field name=&quot;Username&quot; key=&quot;loginUsernameKey&quot; type=&quot;String&quot;
mapToProperty=&quot;Username&quot;&gt;
...rule elements goes here...
&lt;/field&gt;
</code></pre>
<p></p>
<p>
A field element can have the following attributes:
</p>
<ul>
<li>&quot;name&quot; attribute
<ul>
<li>
the name of the field, is required, and must
be unique across the entire group element.
</li>
</ul>
</li>
</ul>
<ul>
<li>&quot;key&quot; attribute
<ul>
<li>
the key of the field, is required, and must
be unique across the entire group element.
</li>
</ul>
</li>
</ul>
<ul>
<li>&quot;type&quot; attribute
<ul>
<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
allowed values.
</li>
</ul>
</li>
</ul>
<ul>
<li>&quot;mapToProperty&quot; attribute
<ul>
<li>
optional, used if you want to map the form
to a business object. Note that the field
names specified in this &quot;field&quot; element
should match the field name of the business
object with appropriate get/set methods.
</li>
</ul>
</li>
</ul>
<p>
For a complete list of valid attributes of the field
element, please see the
<a href="http://turbine.apache.org/turbine-2/services/intake-service.html" class="externalLink">
intake-service document</a> on the Turbine web site.
</p>
</section>
<section><a id="a.3Crule.3E_elements"></a>
<h2>&lt;rule&gt; elements</h2>
<p>
In each field element, you can have rules defined. The
supported rule elements for Intake in Turbine 2.1 are:
</p>
<pre class="prettyprint"><code>
&lt;rule name=&quot;required&quot; value=&quot;true&quot;&gt;Error message for required failed&lt;/rule&gt;
&lt;rule name=&quot;minLength&quot; value=&quot;4&quot;&gt;Error message for required min length failed&lt;/rule&gt;
&lt;rule name=&quot;maxLength&quot; value=&quot;9&quot;&gt;Error message for required max length failed&lt;/rule&gt;
&lt;rule name=&quot;mask&quot; value=&quot;^[0-9]+$&quot;&gt;Error message for regular expression failed&lt;/rule&gt;
&lt;rule name=&quot;notANumberMessage&quot;&gt;Error message for Number fields when the entry is not a number&lt;/rule&gt;
</code></pre>
<p></p>
<p>
For more info on the supported rules, please see the
<a href="http://turbine.apache.org/turbine-2/services/intake-service.html" class="externalLink">
intake-service document</a> on the Turbine web site:
</p>
</section>
</section>
<section><a id="Step_3.3A_Create_a_business_object_to_represent_the_intake_group_we_are_working_with_.28this_is_optional.29."></a>
<h1>Step 3: Create a business object to represent the intake group we are working with (this is optional).</h1>
<p>
The business object is basically a Java class that has get and
set methods for each of the object's fields, and these get and
set method names should match the field names specified in the
intake.xml file (whether we stay with the default behaviour of
matching the field names in intake.xml and the business object
or we use the mapToProperty attribute in the &quot;field&quot; element).
Note it is required to use the mapToObject property in the group
element to use this feature.
</p>
<p>
The business object also has to implement the
org.apache.turbine.om.Retrievable interface. The Retrievable
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 &quot;_0&quot; which is the default key used by Intake (as of
Turbine 2.1). 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
Action class (the benefit would be that you'll be able to use
more than 1 business object in the same template if you get/set
the different query keys).
</p>
<p>
Here is an example of how to use the setQueryKey() and
getQueryKey() methods of the business object that implements
the Retrievable interface:
</p>
<p>
In the template file, e.g. myform.vm:
</p>
<pre class="prettyprint"><code>
#set($loginForm = $mytool.getLoginFormInstance())
$loginForm.setQueryKey(&quot;abc&quot;)
#set($loginGroup = $intake.LoginGroup.mapTo($loginForm))
</code></pre>
<p></p>
<p>
In the Action class:
</p>
<pre class="prettyprint"><code>
// This key has to match the one in the template
String key = &quot;abc&quot;;
Group group = intake.get(&quot;LoginGroup&quot;, key);
</code></pre>
<p></p>
</section>
<section><a id="Step_4.3A_Create_the_Turbine_Action_to_handle_the_form_submission."></a>
<h1>Step 4: Create the Turbine Action to handle the form submission.</h1>
<p>
Depending on the method you use, the code in the action will
need to obtain the corresponding group object from intake. The
following examples will demonstrate the ideas.
</p>
<p>
Here is an example the code in a Turbine Action, using intake
without mapping to a business object (vanilla method):
</p>
<pre class="prettyprint"><code>
/**
* Performs user login
*/
public void doLogin(RunData data, Context context)
throws Exception {
// Get intake group
IntakeTool intake =
(IntakeTool)context.get(&quot;intake&quot;);
// Notice how this gets the group named &quot;LoginGroup&quot; as defined in
// the intake.xml file, and gets it using the default key
// IntakeTool.DEFAULT_KEY (which is &quot;_0&quot;).
Group group = intake.get(&quot;LoginGroup&quot;, IntakeTool.DEFAULT_KEY);
// Check if group fields are valid and if they are not, then return.
// Intake will handle the validation error and display the
// corresponding error messages to the user but if you use the setPage()
// mechanism to get the &quot;next template&quot; then you must now set the
// template to be the same one as the user was filling out. Otherwise
// the user will just see the next template. See the &quot;important note&quot;
// in step 1.
if (!group.isAllValid()) {
Log.debug(&quot;Group elements INVALID&quot;);
setTemplate(data, &quot;Login.vm&quot;);
return;
} 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
// on successful validation.
setTemplate(data, &quot;LoginSuccess.vm&quot;);
}
// This gets the value of the &quot;Username&quot; field from the group object
String username = (String)group.get(&quot;Username&quot;).getValue();
String password = (String)group.get(&quot;Password&quot;).getValue();
// Now you will be able to use the username and password variable in
// the rest of the Turbine Action.
...
}
</code></pre>
<p></p>
<p>
Here is example code in a Turbine Action, using the intake
group's default mapToObject setting (this is the same whether
or not you use the field's mapToProperty attribute):
</p>
<pre class="prettyprint"><code>
/**
* Performs user login
*/
public void doLogin(RunData data, Context context)
throws Exception {
// Get intake group
IntakeTool intake =
(IntakeTool)context.get(&quot;intake&quot;);
Group group = intake.get(&quot;LoginGroup&quot;, IntakeTool.DEFAULT_KEY);
// Check if group fields are valid and if they are not, then return.
// Intake will handle the validation error and display the
// corresponding error messages to the user but if you use the setPage()
// mechanism to get the &quot;next template&quot; then you must now set the
// template to be the same one as the user was filling out. Otherwise
// the user will just see the next template. See the &quot;important note&quot;
// in step 1.
if (!group.isAllValid()) {
Log.debug(&quot;Group elements INVALID&quot;);
setTemplate(data, &quot;Login.vm&quot;);
return;
} 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
// on successful validation.
setTemplate(data, &quot;LoginSuccess.vm&quot;);
}
// Instaniate a business object that represents the form
LoginForm loginForm = new LoginForm();
// Set the properties of the form given the field data in the group
// (i.e. populate the business object)
group.setProperties(loginForm);
// Now the business object is populated accordingly. You can use it
// for whatever purpose in the rest of the Turbine Action.
...
}
</code></pre>
<p></p>
</section>
<section><a id="Removing_Intake_information_from_the_request"></a>
<h1>Removing Intake information from the request</h1>
<p>
Intake data is retained in the request in order to allow for the
possibility that it will be re-presented to the user on the next
page. Normally this is desirable behaviour - there may have been
an error in the data so you want to redisplay it. There is a
possibility however that you might want to reuse the same group
on either the same or a different page after fully processing
the data; in this case it may be undesirable to redisplay the
previously entered data. The prime example of this is where a
page includes a repeating group of records and provides an
opportunity to add a further record using the default group,
returning to the same page after each record is added. In this
situation you will find that the default group needs to be
removed from the request, otherwise the data entered on the
previous page will be redisplayed.
</p>
<p>
Intake allows for this by providing a way of removing the data
that is no longer appropriate to display. Simply:
</p>
<pre class="prettyprint"><code>
intake.remove(group);
</code></pre>
<p></p>
<p>
... where &quot;intake&quot; is a reference to your IntakeTool and &quot;group&quot;
is a reference to the group you wish to remove from the
request. You would do this after the new record had been
validated and added to the database.
</p>
<p>
It will be rare that you actually need to do this - it is
required only in situations where the same group is used on
subsequent pages after the data has been fully processed (it
should be pretty obvious when this is the case).
</p>
</section>
</main>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>© 2000–2025
<a href="https://www.apache.org/">The Apache Software Foundation</a>
</p>
</div>
</div>
</footer>
</body>
</html>