Introduction

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.

To use intake, the following steps are required:

1. Create your turbine template with a form.
2. Create the intake.xml file.
3. Create a business object to represent the intake group we are working with (this is optional).
4. Create the Turbine Action to handle the form submission.

Some additional information concerning removing Intake group information from the request is included at the bottom of this document.

Step 1: Create your turbine template with a form

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.

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 "login form":

#set($loginGroup = $intake.LoginGroup.Default)
            

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 "LoginGroup" 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 "Default" part obtains a generic default intake group object. Or in other words, this resolves to IntakeTool.get(String groupName) with the groupName being "LoginGroup". Also, you can re-write the statement as $intake.get("LoginGroup").getDefault() in your template.

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):

#set($loginGroup = $intake.LoginGroup.mapTo($mytool.getInstanceLoginForm()))
            

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 "getter" 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 "$mytool" (you can make your own tool to instantiate an instance of your business object similar to this example).

So, depending on the method you use above, the corresponding Turbine Action code will need to "cooperate" accordingly. We'll discuss this later in step 4.

Near the end of the form (before you close the "form" tag) include the following line:

$intake.declareGroups()
            

What this does is to fill in hidden form fields into the form for use by intake.

In order to use Turbine's Action event system, the submit buttons must adhere to the naming specification defined by Turbine's Action event system.

<form name="myForm" method="POST"
      action="$link.setAction('LoginAction').setPage('NextTemplate.vm')">
    ...
</form>
                

Step 2: Create the intake.xml file

The intake.xml file specifies the validation rules required to be satisfied in order for the form to be accepted. The file has a "root" XML element of "input-data" and in that would be "group" elements.

Here is an example of the element (with no other sub-elements):

<!DOCTYPE input-data SYSTEM
           "http://turbine.apache.org/dtd/intake_2_3.dtd">
<input-data basePackage="ca.yorku.devteam.inca.clients.skeleton.">
    ...group elements goes here...
</input-data>
            

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 "group" and "field" elements can optionally map to. The trailing period is REQUIRED.

<group name="LoginGroup" key="loginGroupKey" mapToObject="LoginForm">
    ...field elements goes here...
</group>
                

<field name="Username" key="loginUsernameKey" type="String"
        mapToProperty="Username">
    ...rule elements goes here...
</field>
                

<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>
<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>

                

Step 3: Create a business object to represent the intake group we are working with (this is optional).

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 "field" element). Note it is required to use the mapToObject property in the group element to use this feature.

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 "_0" 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).

Here is an example of how to use the setQueryKey() and getQueryKey() methods of the business object that implements the Retrievable interface:

In the template file, e.g. myform.vm:

#set($loginForm = $mytool.getLoginFormInstance())
$loginForm.setQueryKey("abc")
#set($loginGroup = $intake.LoginGroup.mapTo($loginForm))
            

In the Action class:

// This key has to match the one in the template
String key = "abc";
Group group = intake.get("LoginGroup", key);
            

Step 4: Create the Turbine Action to handle the form submission.

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.

Here is an example the code in a Turbine Action, using intake without mapping to a business object (vanilla method):

/**
 * Performs user login
 */
public void doLogin(RunData data, Context context)
        throws Exception {
    // Get intake group
    IntakeTool intake =
            (IntakeTool)context.get("intake");

    // Notice how this gets the group named "LoginGroup" as defined in
    // the intake.xml file, and gets it using the default key
    // IntakeTool.DEFAULT_KEY (which is "_0").
    Group group = intake.get("LoginGroup", 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 "next template" 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 "important note"
    // in step 1.
    if (!group.isAllValid()) {
        Log.debug("Group elements INVALID");
        setTemplate(data, "Login.vm");
        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, "LoginSuccess.vm");
    }

    // This gets the value of the "Username" field from the group object
    String username = (String)group.get("Username").getValue();
    String password = (String)group.get("Password").getValue();

    // Now you will be able to use the username and password variable in
    // the rest of the Turbine Action.
    ...
}
            

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):

/**
 * Performs user login
 */
public void doLogin(RunData data, Context context)
        throws Exception {
    // Get intake group
    IntakeTool intake =
            (IntakeTool)context.get("intake");
    Group group = intake.get("LoginGroup", 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 "next template" 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 "important note"
    // in step 1.
    if (!group.isAllValid()) {
        Log.debug("Group elements INVALID");
        setTemplate(data, "Login.vm");
        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, "LoginSuccess.vm");
    }

    // 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.
    ...
}
            

Removing Intake information from the request

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.

Intake allows for this by providing a way of removing the data that is no longer appropriate to display. Simply:

intake.remove(group);
            

... where "intake" is a reference to your IntakeTool and "group" 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.

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).