@Events(value={"prepareForRender","prepare","prepareForSubmit","validate","submit","failure","success","canceled"}) @SupportsInformalParameters public class Form extends Object implements ClientElement, FormValidationControl
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 ComponentAction
s), 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.BeanEditForm
,
Errors
,
FormFragment
,
Label
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. | 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. |
Name | Description |
---|---|
canceled | |
failure | |
prepare | |
prepareForRender | |
prepareForSubmit | |
submit | |
success | |
validate |
The following components are Tapestry wrappers around client-side HTML form elements:
Examples of the Form component are provided in the many other pages that discuss specific form control element components, such as Radio andTextField.
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 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.
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.
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.
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"/>
.
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 and Description |
---|
Form() |
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
|
public static final String FORM_DATA
public static final String SUBMITTING_ELEMENT_ID
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.public static final StreamPageContent STREAM_ACTIVE_PAGE_CONTENT
@Parameter(value="defaultTracker") protected ValidationTracker tracker
public Form()
public ValidationTracker getDefaultTracker()
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.public void setDefaultTracker(ValidationTracker defaultTracker)
protected void afterSuccessOrFailure()
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.protected void beforeProcessSubmit(EventContext context)
onAction(org.apache.tapestry5.EventContext)
before any other setup.
This implementation does nothing.context
- as passed to onAction()
protected void afterValidate()
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.public void recordError(String errorMessage)
FormValidationControl
ValidationTracker.recordError(String)
.recordError
in interface FormValidationControl
public void recordError(Field field, String errorMessage)
FormValidationControl
ValidationTracker.recordError(Field, String)
.recordError
in interface FormValidationControl
public boolean getHasErrors()
FormValidationControl
ValidationTracker
contains any errors
.getHasErrors
in interface FormValidationControl
public boolean isValid()
FormValidationControl
ValidationTracker
does not contain any errors
.isValid
in interface FormValidationControl
public void clearErrors()
FormValidationControl
ValidationTracker.clear()
.clearErrors
in interface FormValidationControl
public String getClientId()
getClientId
in interface ClientElement
${project.version} - Copyright © 2003-2015 The Apache Software Foundation.