The Velocity Project < Velocity Tools - Struts >

Velocity Tools

VelocityStruts

VelocityStruts Tools

Other Subprojects

FormTool Reference Documentation

Struts has support to parse incoming HTTP requests and populate a Java bean with the submitted request parameters. The same Java bean is used to populate forms with initial values. Additionally, a hook allows the application developer to include automatic form validation code.

FormTool provides miscellaneous methods to work with forms and form bean in the context of Struts applications.

Class
 org.apache.velocity.tools.struts.FormTool
Name
 $form (this is the recommended name of the tool in the Velocity context)
Toolbox Configuration Example
 
<tool>
  <key>form</key>
  <scope>request</scope>
  <class>org.apache.velocity.tools.struts.FormTool</class>
</tool>
Author(s)
  Gabriel Sidler
Method Overview
getBean() Retrieve and return the form bean associated with this request.
getCancelName() Returns the query parameter name under which a cancel button press must be reported if form validation is to be skipped.
getName() Returns the form bean name associated with this action mapping.
getToken() Retrieves and returns the transaction control token for this session.
getTokenName() Returns the query parameter name under which a transaction token must be reported.

getBean()

Retrieve and return the form bean associated with this request.

ActionForm getBean()

Returns
The ActionForm associated with this request/session or null if there is no form bean associated with this mapping.

This is a convenience method. The form bean is automatically available in the Velocity context under the name defined in the Struts configuration.

If the form bean is used repeatedly, it is recommended to create a local variable referencing the bean rather than calling getBean() multiple times.

## Populating an input field with a default value
<input type="text" name="username" value="$form.getBean().username">

## The same can be written as
<input type="text" name="username" value="$form.bean.username">

## For repeated use create a local reference
#set ($defaults = $form.bean)
<input type="text" name="username" value="$defaults.username">

## Accessing the form using the form name defined in struts-config.xml
## Velocity searches the request and session attributes for loginForm
<input type="text" name="username" value="$loginForm.username">


getCancelName()

Returns the query parameter name under which a cancel button press must be reported if form validation is to be skipped.

String getCancelName()

Returns
The value of org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY

If a request contains a request parameter with key equal to the return value of this method, then automatic form validation is skipped. A typical application case is to use this magic string for the name attribute of a cancel button in a form. If this button is pressed, automatic form validation is skipped. If automatic form validation is not used, this magic string is irrelevant.

## A cancel button
<input type="submit" name="$form.getCancelName()" value="Cancel">

## Can also be written as
<input type="submit" name="$form.cancelName" value="Cancel">

This produces the following output:

<input type="submit" name="org.apache.struts.taglib.html.CANCEL"
value="Cancel">


getName()

Returns the form bean name associated with this action mapping.

String getName()

Returns
The name of the ActionForm associated with this request or null if there is no form bean associated with this mapping.


getToken()

Retrieves and returns the transaction control token for this session.

String getToken()

Returns
The token String or null if no token exists.
See Also
Method getTokenName() for examples.


getTokenName()

Returns the query parameter name under which a transaction token must be reported.

int getTokenName()

Returns
The value of org.apache.struts.taglib.html.Constants.TOKEN_KEY
See Also
JavaDoc of class org.apache.struts.action.Action for more information on the transaction token mechanism (I don't know of any better documentation of this Struts feature).
## A hidden form field with the transaction token
<input type="hidden" name="$form.getTokenName()"
value="$form.getToken()">

## Can also be written as
<input type="hidden" name="$form.tokenName"
value="$form.token">

This produces output similar to:

<input type="hidden" name="org.apache.struts.taglib.html.TOKEN"
value="84c29b4dea56ecf69524ef6b965c5e80">



Copyright © 1999-2003, Apache Software Foundation