Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 java.lang.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 `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.

See Also:
  `BeanEditForm`, `Errors`, `FormFragment`, `Label`

Component Parameters
Name | Description | Type | Flags | Default | Default Prefix | Since
--- | --- | --- | --- | --- | --- | ---
autofocus | 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). | boolean |  |  | prop |
clientValidation | Controls when client validation occurs on the client, if at all. Defaults to org.apache.tapestry5.corelib.ClientValidation#BLUR. | org.apache.tapestry5.corelib.ClientValidation | Not Null |  | literal |
context | 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. | Object |  |  | prop |
secure | 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. | boolean |  |  | prop |
tracker | The object which will record user input and validation errors. The object must be persistent between requests (since the form submission and validation occurs in a component event request and the subsequent render occurs in a render request). The default is a persistent property of the Form component and this is sufficient for nearly all purposes (except when a Form is rendered inside a loop). | org.apache.tapestry5.ValidationTracker |  | defaultTracker | prop |
validate | 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. | Object |  |  | prop |
validationId | 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. | String |  |  | prop |
zone | 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. | String |  |  | literal |

Events:

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
`static java.lang.String` | `FORM_DATA` Query parameter name storing form data (the serialized commands needed to process a form submission).
`static java.lang.String` | `SUBMITTING_ELEMENT_ID` Used by `Submit`, etc., to identify which particular client-side element (by element id) was responsible for the submission.

Constructor Summary
`Form()`

Method Summary
`void` | `clearErrors()` Invokes `ValidationTracker.clear()`.
`java.lang.String` | `getClientId()` Forms use the same value for their name and their id attribute.
`ValidationTracker` | `getDefaultTracker()`
`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, java.lang.String errorMessage)` A convienience for invoking `ValidationTracker.recordError(Field, String)`.
`void` | `recordError(java.lang.String errorMessage)` A convienience for invoking `ValidationTracker.recordError(String)`.
`void` | `setDefaultTracker(ValidationTracker defaultTracker)`

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 java.lang.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 java.lang.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

Constructor Detail

### Form

    public Form()

Method Detail

### getDefaultTracker

    public ValidationTracker getDefaultTracker()

### setDefaultTracker

    public void setDefaultTracker(ValidationTracker defaultTracker)

### recordError

    public void recordError(java.lang.String errorMessage)

  Description copied from interface: `FormValidationControl`
  A convienience for invoking `ValidationTracker.recordError(String)`.

  Specified by:
    `recordError` in interface `FormValidationControl`

### recordError

    public void recordError(Field field,
                            java.lang.String errorMessage)

  Description copied from interface: `FormValidationControl`
  A convienience 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 java.lang.String getClientId()

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

  Specified by:
    `getClientId` in interface `ClientElement`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2012 The Apache Software Foundation.