org.apache.tapestry5.corelib.components

Class Form

java.lang.Object

org.apache.tapestry5.corelib.components.Form

All Implemented Interfaces:

ClientElement, FormValidationControl

@Events(value={"prepareForRender","prepare","prepareForSubmit","validate","submit","failure","success","canceled"})
 @SupportsInformalParameters
public class Form
extends Object
implements ClientElement, FormValidationControl

An HTML form, which will enclose other components to render out the various types of fields. A Form triggers many notification events. When it renders, it triggers a EventConstants.PREPARE_FOR_RENDER notification, followed by a EventConstants.PREPARE notification. When the form is submitted, the component triggers several notifications: first a EventConstants.PREPARE_FOR_SUBMIT, then a EventConstants.PREPARE: these allow the page to update its state as necessary to prepare for the form submission. The Form component then determines if the form was cancelled (see SubmitMode.CANCEL). If so, a EventConstants.CANCELED event is triggered. Next come notifications to contained components (or more accurately, the execution of stored ComponentActions), to allow each component to retrieve and validate submitted values, and update server-side properties. This is based on the t:formdata query parameter, which contains serialized object data (generated when the form initially renders). Once the form data is processed, the next step is to trigger the EventConstants.VALIDATE, which allows for cross-form validation. After that, either a EventConstants.SUCCESS OR EventConstants.FAILURE event (depending on whether the ValidationTracker has recorded any errors). Lastly, a EventConstants.SUBMIT event, for any listeners that care only about form submission, regardless of success or failure. For all of these notifications, the event context is derived from the context component parameter. This context is encoded into the form's action URI (the parameter is not read when the form is submitted, instead the values encoded into the form are used). While rendering, or processing a Form submission, the Form component places a FormSupport object into the environment, so that enclosed components can coordinate with the Form component. It also places a ValidationTracker into the environment during both render and submission. During submission it also pushes a Heartbeat into the environment, which is ended just before deferred FormSupport operations are executed.

See Also:

BeanEditForm, Errors, FormFragment, Label

Component Parameters

Name	Type	Flags	Default	Default Prefix
async	boolean	Since 5.4		prop
	When true, the the form will submit as an asynchronous request (via XmlHttpRequest); the event handler methods can make use of the org.apache.tapestry5.services.ajax.AjaxResponseRenderer in order to force content updates to the client. This is used as an alternative to placing the form inside a org.apache.tapestry5.corelib.components.Zone and binding the zone parameter.
autofocus	boolean			prop
	If true (the default), then the JavaScript will be added to position the cursor into the form. The field to receive focus is the first rendered field that is in error, or required, or present (in that order of priority).
clientValidation	org.apache.tapestry5.corelib.ClientValidation	Not Null		literal
	Controls when client validation occurs on the client, if at all. Defaults to org.apache.tapestry5.corelib.ClientValidation#SUBMIT. org.apache.tapestry5.corelib.ClientValidation#BLUR was the default, prior to Tapestry 5.4, but is no longer supported.
context	Object			prop
	The context for the link (optional parameter). This list of values will be converted into strings and included in the URI. The strings will be coerced back to whatever their values are and made available to event handler methods.
secure	boolean			prop
	If true, then the Form's action will be secure (using an absolute URL with the HTTPs scheme) regardless of whether the containing page itself is secure or not. This parameter does nothing when (which is often the case in development mode). This only affects how the Form's action attribute is rendered, there is not (currently) a check that the form is actually submitted securely.
validate	Object			prop
	Object to validate during the form submission process. The default is the Form component's container. This parameter should only be used in combination with the Bean Validation Library.
validationId	String			prop
	Prefix value used when searching for validation messages and constraints. The default is the Form component's id. This is overridden by org.apache.tapestry5.corelib.components.BeanEditForm.
zone	String			literal
	Binding the zone parameter will cause the form submission to be handled as an Ajax request that updates the indicated zone. Often a Form will update the same zone that contains it.

Component Events

Name	Description
canceled
failure
prepare
prepareForRender
prepareForSubmit
submit
success
validate

Form Control Element Components

The following components are Tapestry wrappers around client-side HTML form elements:

• Checkbox
• DateField
• Palette
• PasswordField
• Radio and RadioGroup
• Select
• Submit
• TextArea
• TextField

Examples

Examples of the Form component are provided in the many other pages that discuss specific form control element components, such as Radio andTextField.

Notes

The Form component generates a seemingly bewildering number of events, designed to address a wide range of needs. The goal is to give you as the developer the tools necessary to effeciently manage state.

All of the events that are triggered will pass along the values defined by the context parameter. Most often, there is no context, or the context is a single value (a primary key used to identify the object being updated by the form).

Render Events

Render event handler methods should not return a value, doing so will be an error. The methods are intended to allow the page to convert a primary key stored in the context back into an object ready to have its properties updated by the Form.

The context passed to component event handler methods is provided by reading the context parameter.

• prepareForRender
• prepare

Submit Events

Submit events may return a navigational value, which will abort any remaining processing of the form submission.

The context provided to component event handler methods originates in the form submission (it is stored in hidden form fields); the context parameter is not read during a form submission.

• prepareForSubmit
• prepare
• validate
• failure or success
• submit

The validate event is to allow the page to perform cross-field validation. The validateForm event is a deprecated name for the validate event (it currently exists only for backwards compatibility). The failure or success event is fired based on whether there are or are not any validation errors.

Form Ids

It is considered a best practice to give explicit ids to Form components, and form control element components. These ids propagate down to the client side as element names and/or ids, and eventually show up as query parameters when the form is submitted.

To achieve a more RESTful URL scheme, give the form component an id based on what it does rather than what data it updates, thus <t:form t:id="search"/> rather than <t:form t:id="searchData"/> or <t:form t:id="searchForm"/>.

Field Summary

Fields

Modifier and Type	Field and Description
static String	FORM_DATA Query parameter name storing form data (the serialized commands needed to process a form submission).
static StreamPageContent	STREAM_ACTIVE_PAGE_CONTENT
static String	SUBMITTING_ELEMENT_ID Used by Submit, etc., to identify which particular client-side element (by element id) was responsible for the submission.
protected ValidationTracker	tracker The object which will record user input and validation errors.

Constructor Summary

Constructors

Constructor and Description
Form()

Method Summary

Modifier and Type	Method and Description
protected void	afterSuccessOrFailure() A hook invoked from onAction(org.apache.tapestry5.EventContext) after the EventConstants.SUBMIT or EventConstants.FAILURE event has been triggered.
protected void	afterValidate() A hook invoked from onAction(org.apache.tapestry5.EventContext) after the EventConstants.VALIDATE event has been triggered, and before the tracker has been cleared.
protected void	beforeProcessSubmit(EventContext context) A hook invoked from onAction(org.apache.tapestry5.EventContext) before any other setup.
void	clearErrors() Invokes ValidationTracker.clear().
String	getClientId() Forms use the same value for their name and their id attribute.
ValidationTracker	getDefaultTracker() Returns an instance of ValidationTrackerImpl, lazily creating it as needed.
boolean	getHasErrors() Returns true if the form's ValidationTracker contains any errors.
boolean	isValid() Returns true if the form's ValidationTracker does not contain any errors.
void	recordError(Field field, String errorMessage) A convenience method for invoking ValidationTracker.recordError(Field, String).
void	recordError(String errorMessage) A convenience method for invoking ValidationTracker.recordError(String).
void	setDefaultTracker(ValidationTracker defaultTracker) Deprecated. In 5.4; previously used only for testing

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORM_DATA

public static final String FORM_DATA

Query parameter name storing form data (the serialized commands needed to process a form submission).

See Also:

Constant Field Values

SUBMITTING_ELEMENT_ID

public static final String SUBMITTING_ELEMENT_ID

Used by Submit, etc., to identify which particular client-side element (by element id) was responsible for the submission. An empty hidden field is created, as needed, to store this value. Starting in Tapestry 5.3, this is a JSONArray with two values: the client id followed by the client name.

Since:

5.2.0

See Also:

Constant Field Values

STREAM_ACTIVE_PAGE_CONTENT

public static final StreamPageContent STREAM_ACTIVE_PAGE_CONTENT

tracker

@Parameter(value="defaultTracker")
protected ValidationTracker tracker

The object which will record user input and validation errors. When not using the default behavior supplied by the Form component (an immediate re-render of the active page when there are form validation errors), it is necessary to bind this parameter to a persistent value that can be maintained until the active page is re-rendered. See TAP5-1801.

Constructor Detail

Form

public Form()

Method Detail

getDefaultTracker

public ValidationTracker getDefaultTracker()

Returns an instance of ValidationTrackerImpl, lazily creating it as needed. This property is the default for the tracker parameter; the property (as of Tapestry 5.4) is not persistent.

Returns:

per-request cached instance

setDefaultTracker

public void setDefaultTracker(ValidationTracker defaultTracker)

Deprecated. In 5.4; previously used only for testing

afterSuccessOrFailure

protected void afterSuccessOrFailure()

A hook invoked from onAction(org.apache.tapestry5.EventContext) after the EventConstants.SUBMIT or EventConstants.FAILURE event has been triggered. This method will be invoked regardless of whether the submit or failure event was aborted. This implementation does nothing.

Since:

5.4

beforeProcessSubmit

protected void beforeProcessSubmit(EventContext context)

A hook invoked from onAction(org.apache.tapestry5.EventContext) before any other setup. This implementation does nothing.

Parameters:

context - as passed to onAction()

Since:

5.4

afterValidate

protected void afterValidate()

A hook invoked from onAction(org.apache.tapestry5.EventContext) after the EventConstants.VALIDATE event has been triggered, and before the tracker has been cleared. Only invoked if the valiate event did not abort (that is, the no event handler method returned a value). This implementation does nothing.

Since:

5.4

recordError

public void recordError(String errorMessage)

Description copied from interface: FormValidationControl

A convenience method for invoking ValidationTracker.recordError(String).

Specified by:

recordError in interface FormValidationControl

recordError

public void recordError(Field field,
                        String errorMessage)

Description copied from interface: FormValidationControl

A convenience method for invoking ValidationTracker.recordError(Field, String).

Specified by:

recordError in interface FormValidationControl

getHasErrors

public boolean getHasErrors()

Description copied from interface: FormValidationControl

Returns true if the form's ValidationTracker contains any errors.

Specified by:

getHasErrors in interface FormValidationControl

isValid

public boolean isValid()

Description copied from interface: FormValidationControl

Returns true if the form's ValidationTracker does not contain any errors.

Specified by:

isValid in interface FormValidationControl

clearErrors

public void clearErrors()

Description copied from interface: FormValidationControl

Invokes ValidationTracker.clear().

Specified by:

clearErrors in interface FormValidationControl

getClientId

public String getClientId()

Forms use the same value for their name and their id attribute.

Specified by:

getClientId in interface ClientElement

Returns:

a unique id for the element. This value will be unique for any given rendering of a page. This value is intended for use as the id attribute of the client-side element, and will be used with any DHTML/Ajax related JavaScript.