org.apache.tapestry
Interface FormBehavior

All Known Subinterfaces:
FormSupport, IForm
All Known Implementing Classes:
Form, FormSupportImpl, Go, GoFormSupportImpl

public interface FormBehavior

Common interface extended by IForm and FormSupport.

Since:
4.0
Author:
Howard M. Lewis Ship

Method Summary
 void addDeferredRunnable(java.lang.Runnable runnable)
          Adds a deferred runnable, an object to be executed either before the </form> tag is rendered (when rendering), or before the form's listener is invoked (when rewinding).
 void addEventHandler(FormEventType type, java.lang.String functionName)
          Deprecated. Wiring of form event handlers is now managed on the client side. This method may be removed in a future release of Tapestry.
 void addHiddenValue(java.lang.String name, java.lang.String value)
          Adds a hidden field value to be stored in the form.
 void addHiddenValue(java.lang.String name, java.lang.String id, java.lang.String value)
          Adds a hidden field value to be stored in the form.
 java.lang.String getElementId(IFormComponent component)
          Constructs a unique identifier (within the Form).
 java.lang.String getElementId(IFormComponent component, java.lang.String baseId)
          Constructs a unique identifier from the base id.
 boolean isRewinding()
          Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).
 void prerenderField(IMarkupWriter writer, IComponent field, org.apache.hivemind.Location location)
          Pre-renders the specified field, buffering the result for later use by wasPrerendered(IMarkupWriter, IComponent).
 void registerForFocus(IFormComponent field, int priority)
          Registers a field for automatic focus.
 void setEncodingType(java.lang.String encodingType)
          May be invoked by a component to force the encoding type of the form to a particular value.
 boolean wasPrerendered(IMarkupWriter writer, IComponent field)
          Invoked by a form control component (a field) that may have been pre-rendered.
 

Method Detail

addEventHandler

void addEventHandler(FormEventType type,
                     java.lang.String functionName)
Deprecated. Wiring of form event handlers is now managed on the client side. This method may be removed in a future release of Tapestry.

Adds an additional event handler. The type determines when the handler will be invoked, FormEventType.SUBMITis most typical.


addHiddenValue

void addHiddenValue(java.lang.String name,
                    java.lang.String value)
Adds a hidden field value to be stored in the form. This ensures that all of the <input type="hidden"> (or equivalent) are grouped together, which ensures that the output HTML is valid (ie. doesn't have <input> improperly nested with <tr>, etc.).

It is acceptible to add multiple hidden fields with the same name. They will be written in the order they are received.


addHiddenValue

void addHiddenValue(java.lang.String name,
                    java.lang.String id,
                    java.lang.String value)
Adds a hidden field value to be stored in the form. This ensures that all of the <input type="hidden"> (or equivalent) are grouped together, which ensures that the output HTML is valid (ie. doesn't have <input> improperly nested with <tr>, etc.).

It is acceptible to add multiple hidden fields with the same name. They will be written in the order they are received.

Since:
3.0

getElementId

java.lang.String getElementId(IFormComponent component)
Constructs a unique identifier (within the Form). The identifier consists of the component's id, with an index number added to ensure uniqueness.

Simply invokes getElementId(IFormComponent, String)with the component's id.

Note: yes, some confusion on naming here. This is the form element id, which should be (for Tapestry purposes) unique within the rendered form. The IFormComponent.getClientId() is different, and should be unique within the rendered page.


getElementId

java.lang.String getElementId(IFormComponent component,
                              java.lang.String baseId)
Constructs a unique identifier from the base id. If possible, the id is used as-is. Otherwise, a unique identifier is appended to the id.

This method is provided simply so that some components ( ImageSubmit) have more specific control over their names.

Invokes IFormComponent.setName(String)with the result, as well as returning it.

Throws:
StaleLinkException - if, when the form itself is rewinding, the element id allocated does not match the expected id (as allocated when the form rendered). This indicates that the state of the application has changed between the time the form renderred and the time it was submitted.

isRewinding

boolean isRewinding()
Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).


setEncodingType

void setEncodingType(java.lang.String encodingType)
May be invoked by a component to force the encoding type of the form to a particular value.

Throws:
ApplicationRuntimeException - if the current encoding type is not null and doesn't match the provided encoding type
See Also:
Upload

prerenderField

void prerenderField(IMarkupWriter writer,
                    IComponent field,
                    org.apache.hivemind.Location location)
Pre-renders the specified field, buffering the result for later use by wasPrerendered(IMarkupWriter, IComponent). Typically, it is a FieldLabel component that pre-renders an associated field. This little dance is necessary to properly support field labels inside loops, and to handle the portlet action/render request cycle.

Parameters:
writer - the markup writer (from which a nested markup writer is obtained)
field - the field to pre-render. The field is responsible for invoking wasPrerendered(IMarkupWriter, IComponent).
location - an optional location (of the FieldLabel component) used when reporting errors.

wasPrerendered

boolean wasPrerendered(IMarkupWriter writer,
                       IComponent field)
Invoked by a form control component (a field) that may have been pre-rendered. If the field was pre-rendered, then the buffered output is printed into the writer and true is returned. Otherwise, false is returned.

Returns:
true if the field was pre-rendered and should do nothing during its render phase, false if the field should continue as normal.

addDeferredRunnable

void addDeferredRunnable(java.lang.Runnable runnable)
Adds a deferred runnable, an object to be executed either before the </form> tag is rendered (when rendering), or before the form's listener is invoked (when rewinding). Runnables are executed in the order in which they are added.

Parameters:
runnable - the object to execute (which may not be null)

registerForFocus

void registerForFocus(IFormComponent field,
                      int priority)
Registers a field for automatic focus. The goal is for the first field that is in error to get focus; failing that, the first required field; failing that, any field.

Parameters:
field - the field requesting focus
priority - a priority level used to determine whether the registered field becomes the focus field. Constants for this purpose are defined in ValidationConstants.
Since:
4.0