org.apache.tapestry.form
Class Form

java.lang.Object
  org.apache.hivemind.impl.BaseLocatable
      org.apache.tapestry.AbstractComponent
          org.apache.tapestry.form.Form

All Implemented Interfaces:

org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder, FormBehavior, IComponent, IDirect, IDirectEvent, IDynamicInvoker, IForm, Component, IRender

Direct Known Subclasses:

Go

public abstract class Form
extends AbstractComponent
implements IForm

Component which contains form element components. A Form will wrap other components and static HTML, including form components such as TextArea, TextField, Checkbox, etc. [ Component Reference ]

When a form is submitted, it continues through the rewind cycle until after all of its wrapped elements have renderred. As the form component render (in the rewind cycle), they will be updating properties of the containing page and notifying thier listeners. Again: each form component is responsible not only for rendering HTML (to present the form), but for handling it's share of the form submission.

Only after all that is done will the Form notify its listener.

Release 4.0 adds two new listeners, getCancel() and getRefresh() and corresponding client-side behavior to force a form to refresh (update, bypassing input field validation) or cancel (update immediately).

Author:

Howard Lewis Ship, David Solis

Field Summary

Fields inherited from class org.apache.tapestry.AbstractComponent

_body, _bodyCount

Constructor Summary

Form()

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) Adds an additional event handler.
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.
protected void	cleanupAfterRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)after the component renders.
abstract IActionListener	getCancel() cancel parameter, may be null.
abstract IValidationDelegate	getDelegate() delegate parameter, which has a default (starting in release 4.0).
abstract IEngineService	getDirectService() Injected.
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.
abstract JavascriptManager	getJavascriptManager() Injected JavascriptManager which will be used by form to render javascript contributions.
abstract IActionListener	getListener() listener parameter, may be null.
abstract ListenerInvoker	getListenerInvoker() Injected.
abstract String	getMethod() method parameter.
String	getName() Returns the name generated for the form.
abstract Integer	getPort() port , may be null.
JSONObject	getProfile() The javascript object profile being built by this context to validate/translate form values.
abstract IActionListener	getRefresh() refresh parameter, may be null.
boolean	getRequiresSession() Returns true if the stateful parameter is bound to a true value.
abstract WebResponse	getResponse() Injected.
abstract String	getScheme() scheme parameter, may be null.
abstract IActionListener	getSuccess() success parameter, may be null.
boolean	isFormFieldUpdating() Checks to see if a form field has been updated.
boolean	isRewinding() Indicates to any wrapped form components that they should respond to the form submission.
abstract boolean	isStateful() stateful parameter.
protected FormSupport	newFormSupport(IMarkupWriter writer, IRequestCycle cycle) Returns a new instance of FormSupportImpl.
String	peekClientId(IFormComponent component) Used internally to "peek" at what the next generated client id will be for the given component when it renders.
protected void	prepareForRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)to prepare the component to render.
void	prerenderField(IMarkupWriter writer, IComponent field, org.apache.hivemind.Location location) Pre-renders the specified field, buffering the result for later use by FormBehavior.wasPrerendered(IMarkupWriter, IComponent).
void	registerForFocus(IFormComponent field, int priority) Registers a field for automatic focus.
protected void	renderComponent(IMarkupWriter writer, IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)to actually render the component (with any parameter values already set).
void	rewind(IMarkupWriter writer, IRequestCycle cycle) Simply invokes AbstractComponent.render(IMarkupWriter, IRequestCycle).
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).
void	trigger(IRequestCycle cycle) Method invoked by the direct service.
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.

Methods inherited from class org.apache.tapestry.AbstractComponent

addAsset, addBody, addComponent, checkActiveLock, enterActiveState, equals, finishLoad, finishLoad, generateClientId, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getBody, getBodyCount, getBoundId, getClientId, getComponent, getComponents, getContainedComponent, getContainedRenderers, getContainer, getEventInvoker, getExtendedId, getId, getIdPath, getInnerRenderers, getListeners, getMessages, getNamespace, getPage, getRenderWorker, getSpecification, getSpecifiedId, getTemplateTagName, hasEvents, hashCode, isInActiveState, isParameterBound, isRendering, pageEndRender, peekClientId, render, renderBody, renderIdAttribute, renderInformalParameters, setBinding, setClientId, setContainedComponent, setContainer, setHasEvents, setId, setNamespace, setPage, setTemplateTagName, toString, triggerEvent

Methods inherited from class org.apache.hivemind.impl.BaseLocatable

getLocation, setLocation

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.tapestry.IForm

getFocus, isClientValidationEnabled

Methods inherited from interface org.apache.tapestry.IComponent

addAsset, addBody, addComponent, enterActiveState, finishLoad, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getClientId, getComponent, getComponents, getContainedComponent, getContainer, getEventInvoker, getExtendedId, getId, getIdPath, getListeners, getMessages, getNamespace, getPage, getSpecification, getSpecifiedId, getTemplateTagName, isRendering, peekClientId, renderBody, setBinding, setClientId, setContainedComponent, setContainer, setId, setNamespace, setPage, setTemplateTagName

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

getLocation

Methods inherited from interface org.apache.tapestry.IDynamicInvoker

getUpdateComponents, isAsync, isJson

Constructor Detail

Form

public Form()

Method Detail

isRewinding

public boolean isRewinding()

Indicates to any wrapped form components that they should respond to the form submission.

Specified by:

isRewinding in interface FormBehavior

Returns:

True if the form is rewinding, false otherwise.

Throws:

org.apache.hivemind.ApplicationRuntimeException - if not rendering.

getDirectService

public abstract IEngineService getDirectService()

Injected.

Since:

4.0

getRequiresSession

public boolean getRequiresSession()

Returns true if the stateful parameter is bound to a true value. If stateful is not bound, also returns the default, true.

Since:

1.0.1

getElementId

public 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(org.apache.tapestry.form.IFormComponent, java.lang.String)with the component's id.

Specified by:

getElementId in interface FormBehavior

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.

Since:

1.0.2

getElementId

public 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.

Specified by:

getElementId in interface FormBehavior

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.

Since:

1.0.3

peekClientId

public 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).

Specified by:

peekClientId in interface FormBehavior

Parameters:

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

Returns:

The next possible client ID for the component.

getName

public String getName()

Returns the name generated for the form. This is used to faciliate components that write JavaScript and need to access the form or its contents.

This value is generated when the form renders, and is not cleared. If the Form is inside a ForBean, this will be the most recently generated name for the Form.

This property is exposed so that sophisticated applications can write JavaScript handlers for the form and components within the form.

Specified by:

getName in interface IForm

See Also:

AbstractFormComponent.getName()

prepareForRender

protected void prepareForRender(IRequestCycle cycle)

Description copied from class: AbstractComponent

Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)to prepare the component to render. This implementation sets JavaBeans properties from matching bound parameters. The default implementation of this method is empty.

Overrides:

prepareForRender in class AbstractComponent

Since:

3.0 *

cleanupAfterRender

protected void cleanupAfterRender(IRequestCycle cycle)

Description copied from class: AbstractComponent

Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)after the component renders.

Overrides:

cleanupAfterRender in class AbstractComponent

renderComponent

protected void renderComponent(IMarkupWriter writer,
                               IRequestCycle cycle)

Description copied from class: AbstractComponent

Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)to actually render the component (with any parameter values already set). This is the method that subclasses must implement.

Specified by:

renderComponent in class AbstractComponent

newFormSupport

protected FormSupport newFormSupport(IMarkupWriter writer,
                                     IRequestCycle cycle)

Returns a new instance of FormSupportImpl.

addEventHandler

public void addEventHandler(FormEventType type,
                            String functionName)

Adds an additional event handler.

Specified by:

addEventHandler in interface FormBehavior

Parameters:

type - Type of event to add.

functionName - Name of the javascript function being added.

Since:

1.0.2

rewind

public void rewind(IMarkupWriter writer,
                   IRequestCycle cycle)

Simply invokes AbstractComponent.render(IMarkupWriter, IRequestCycle).

Specified by:

rewind in interface IForm

Since:

1.0.2

trigger

public void trigger(IRequestCycle cycle)

Method invoked by the direct service.

Specified by:

trigger in interface IDirect

Parameters:

cycle - The current request.

Since:

1.0.2

getResponse

public abstract WebResponse getResponse()

Injected.

getDelegate

public abstract IValidationDelegate getDelegate()

delegate parameter, which has a default (starting in release 4.0).

Specified by:

getDelegate in interface IForm

getListener

public abstract IActionListener getListener()

listener parameter, may be null.

getSuccess

public abstract IActionListener getSuccess()

success parameter, may be null.

getCancel

public abstract IActionListener getCancel()

cancel parameter, may be null.

getRefresh

public abstract IActionListener getRefresh()

refresh parameter, may be null.

getMethod

public abstract String getMethod()

method parameter.

isStateful

public abstract boolean isStateful()

stateful parameter.

Specified by:

isStateful in interface IDirect

Specified by:

isStateful in interface IDirectEvent

Overrides:

isStateful in class AbstractComponent

Returns:

Whether or not invocation should include state information and validate that a valid session exists when triggered.

getScheme

public abstract String getScheme()

scheme parameter, may be null.

getPort

public abstract Integer getPort()

port , may be null.

setEncodingType

public void setEncodingType(String encodingType)

Description copied from interface: FormBehavior

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

Specified by:

setEncodingType in interface FormBehavior

Parameters:

encodingType - The encoding type to set.

See Also:

Upload

addHiddenValue

public void addHiddenValue(String name,
                           String value)

Description copied from interface: FormBehavior

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.

Specified by:

addHiddenValue in interface FormBehavior

Parameters:

name - The name of the hidden input.

value - The value to store in the hidden field.

Since:

3.0

addHiddenValue

public void addHiddenValue(String name,
                           String id,
                           String value)

Description copied from interface: FormBehavior

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.

Specified by:

addHiddenValue in interface FormBehavior

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

prerenderField

public void prerenderField(IMarkupWriter writer,
                           IComponent field,
                           org.apache.hivemind.Location location)

Description copied from interface: FormBehavior

Pre-renders the specified field, buffering the result for later use by FormBehavior.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.

Specified by:

prerenderField in interface FormBehavior

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 FormBehavior.wasPrerendered(IMarkupWriter, IComponent).

location - an optional location (of the FieldLabel component) used when reporting errors.

wasPrerendered

public boolean wasPrerendered(IMarkupWriter writer,
                              IComponent field)

Description copied from interface: FormBehavior

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.

Specified by:

wasPrerendered in interface FormBehavior

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

public boolean wasPrerendered(IComponent field)

Description copied from interface: FormBehavior

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

Specified by:

wasPrerendered in interface FormBehavior

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

public void addDeferredRunnable(Runnable runnable)

Description copied from interface: FormBehavior

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.

Specified by:

addDeferredRunnable in interface FormBehavior

Parameters:

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

Since:

4.0

getListenerInvoker

public abstract ListenerInvoker getListenerInvoker()

Injected.

Since:

4.0

registerForFocus

public void registerForFocus(IFormComponent field,
                             int priority)

Description copied from interface: FormBehavior

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.

Specified by:

registerForFocus in interface FormBehavior

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.

getProfile

public JSONObject getProfile()

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

Specified by:

getProfile in interface FormBehavior

Returns:

JSONObject profile.

isFormFieldUpdating

public boolean isFormFieldUpdating()

Checks to see if a form field has been updated.

Specified by:

isFormFieldUpdating in interface FormBehavior

Returns:

True if any form field was updated.

See Also:

FormBehavior.setFormFieldUpdating(boolean)

setFormFieldUpdating

public 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.

Specified by:

setFormFieldUpdating in interface FormBehavior

Parameters:

value - The value to set.

getJavascriptManager

public abstract JavascriptManager getJavascriptManager()

Injected JavascriptManager which will be used by form to render javascript contributions.

Returns:

The configured JavascriptManager for this request.