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(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, String functionName) Deprecated. Wiring of form event handlers is now managed on the client side. This method may be removed in Tapestry 4.1.2.
void	addHiddenValue(String name, String value) Adds a hidden field value to be stored in the form.
void	addHiddenValue(String name, String id, String value) Adds a hidden field value to be stored in the form.
String	getElementId(IFormComponent component) Constructs a unique identifier (within the Form).
String	getElementId(IFormComponent component, String baseId) Constructs a unique identifier from the base id.
JSONObject	getProfile() The javascript object profile being built by this context to validate/translate form values.
boolean	isFormFieldUpdating() Checks to see if a form field has been updated.
boolean	isRewinding() Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).
String	peekClientId(IFormComponent component) Used internally to "peek" at what the next generated client id will be for the given component when it renders.
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(String encodingType) May be invoked by a component to force the encoding type of the form to a particular value.
void	setFormFieldUpdating(boolean value) Sets a flag denoting whether or not an IFormComponent field has been updated according to the logic defined in ResponseBuilder.updateComponent(String).
boolean	wasPrerendered(IComponent field) Invoked to check if a particular component has been pre-rendered.
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,
                     String functionName)

Deprecated. Wiring of form event handlers is now managed on the client side. This method may be removed in Tapestry 4.1.2.

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

Parameters:

type - Type of event to add.

functionName - Name of the javascript function being added.

addHiddenValue

void addHiddenValue(String name,
                    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.

Parameters:

name - The name of the hidden input.

value - The value to store in the hidden field.

addHiddenValue

void addHiddenValue(String name,
                    String id,
                    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.

Parameters:

name - The name of the hidden input.

id - The id of the hidden input - should almost always be the same as the name.

value - The value to store in the hidden field.

Since:

3.0

getElementId

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.

Parameters:

component - The component to get the unique id of.

Returns:

The unique id for this component, to be used in rendering name="id" type elements.

getElementId

String getElementId(IFormComponent component,
                    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.

Parameters:

component - The component to generate an element id for.

baseId - The basic id of the component.

Returns:

The form specific unique identifier for the given element. May be the same as the baseId if this is the first render of that specific component.

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.

peekClientId

String peekClientId(IFormComponent component)

Used internally to "peek" at what the next generated client id will be for the given component when it renders. Similar to the logic found in IRequestCycle.peekUniqueId(String).

Parameters:

component - The component to determine the next client id for.

Returns:

The next possible client ID for the component.

isRewinding

boolean isRewinding()

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

Returns:

True if the form is rewinding, false otherwise.

setEncodingType

void setEncodingType(String encodingType)

May be invoked by a component to force the encoding type of the form to a particular value.

Parameters:

encodingType - The encoding type to set.

Throws:

org.apache.hivemind.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.

Parameters:

writer - The markup writer to render with. (may be ignored during dynamic requests)

field - The component to check for pre-rendering.

Returns:

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

wasPrerendered

boolean wasPrerendered(IComponent field)

Invoked to check if a particular component has been pre-rendered.

Parameters:

field - The component to check for pre-rendering. (Such as is done by FieldLabel.

Returns:

True if the component was pre-rendered, false otherwise.

addDeferredRunnable

void addDeferredRunnable(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

getProfile

JSONObject getProfile()

The javascript object profile being built by this context to validate/translate form values.

Returns:

JSONObject profile.

setFormFieldUpdating

void setFormFieldUpdating(boolean value)

Sets a flag denoting whether or not an IFormComponent field has been updated according to the logic defined in ResponseBuilder.updateComponent(String).

Currently this flag is used during ajax/json responses so that cooperating ResponseBuilders can be worked with to ensure form state is properly updated on the client. Specifically, that the hidden form input fields and any associated validation profiles are updated.

Parameters:

value - The value to set.

isFormFieldUpdating

boolean isFormFieldUpdating()

Checks to see if a form field has been updated.

Returns:

True if any form field was updated.

See Also:

setFormFieldUpdating(boolean)