VelocityStruts - FormTool

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.

<tool>
 <key>form</key>
 <scope>request</scope>
 <class>org.apache.velocity.tools.struts.FormTool</class>
</tool>

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.

See Also

The Javadoc for more info.

Retrieve and return the form bean associated with this request.

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

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

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

Returns the form bean name associated with this action mapping.

Returns

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

Retrieves and returns the transaction control token for this session.

Returns

The token String or null if no token exists.

See Also

Method getTokenName() for examples.

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

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