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, IAction, IComponent, IDirect, IForm, IRender

Direct Known Subclasses:

Go

public abstract class Form
extends AbstractComponent
implements IForm, IDirect

Component which contains form element components. Forms use the action or direct services to handle the form submission. 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.

Starting in release 1.0.2, a Form can use either the direct service or the action service. The default is the direct service, even though in earlier releases, only the action service was available.

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 interface org.apache.tapestry.IForm

ATTRIBUTE_NAME

Constructor Summary

Form()

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) Adds an additional event handler.
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.
protected void	cleanupAfterRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)after the component renders.
protected java.lang.String	constructFormNameForActionService(java.lang.String actionId) Construct a form name for use with the action service.
static IForm	get(IRequestCycle cycle) Deprecated. Use TapestryUtils.getForm(IRequestCycle, IComponent) instead.
abstract IEngineService	getActionService() Injected.
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.
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.
protected ILink	getLink(IRequestCycle cycle, java.lang.String actionId) Builds the EngineServiceLink for the form, using either the direct or action service.
abstract IActionListener	getListener() listener parameter, may be null
abstract ListenerInvoker	getListenerInvoker() Injected
abstract java.lang.String	getMethod() method parameter
java.lang.String	getName() Returns the name generated for the form.
abstract java.lang.Integer	getPort() port , may be null
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 java.lang.String	getScheme() scheme parameter, may be null
abstract IActionListener	getSuccess() success parameter, may be null
abstract boolean	isDirect() Returns true if this Form is configured to use the direct service.
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.
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(java.lang.String encodingType) May be invoked by a component to force the encoding type of the form to a particular value.
void	trigger(IRequestCycle cycle) Method invoked by the direct service.
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, finishLoad, finishLoad, format, format, format, format, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getBody, getBodyCount, getComponent, getComponents, getContainedComponent, getContainer, getExtendedId, getId, getIdPath, getListeners, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, isInActiveState, isParameterBound, isRendering, pageEndRender, render, renderBody, renderInformalParameters, setBinding, setContainedComponent, setContainer, setId, setNamespace, setPage, setProperty, toString

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

getLocation, setLocation

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, 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, getComponent, getComponents, getContainedComponent, getContainer, getExtendedId, getId, getIdPath, getListeners, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, isRendering, renderBody, setBinding, setContainedComponent, setContainer, setId, setNamespace, setPage, setProperty

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

Constructor Detail

Form

public Form()

Method Detail

get

public static IForm get(IRequestCycle cycle)

Deprecated. Use TapestryUtils.getForm(IRequestCycle, IComponent) instead.

Returns the currently active IForm, or null if no form is active. This is a convienience method, the result will be null, or an instance of IForm, but not necessarily a Form.

isRewinding

public boolean isRewinding()

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

Specified by:

isRewinding in interface FormBehavior

Throws:

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

getDirectService

public abstract IEngineService getDirectService()

Injected.

Since:

4.0

getActionService

public abstract IEngineService getActionService()

Injected.

Since:

4.0

isDirect

public abstract boolean isDirect()

Returns true if this Form is configured to use the direct service.

This is derived from the direct parameter, and defaults to true if not bound.

Since:

1.0.2

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.

Specified by:

getRequiresSession in interface IAction

Since:

1.0.1

getElementId

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

Specified by:

getElementId in interface FormBehavior

Since:

1.0.2

getElementId

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

Specified by:

getElementId in interface FormBehavior

Since:

1.0.3

getName

public java.lang.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 Foreach, 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. This implementation does nothing.

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. This implementation does nothing.

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

constructFormNameForActionService

protected java.lang.String constructFormNameForActionService(java.lang.String actionId)

Construct a form name for use with the action service. This implementation returns "Form" appended with the actionId.

Since:

4.0

newFormSupport

protected FormSupport newFormSupport(IMarkupWriter writer,
                                     IRequestCycle cycle)

Returns a new instance of FormSupportImpl.

addEventHandler

public void addEventHandler(FormEventType type,
                            java.lang.String functionName)

Adds an additional event handler.

Specified by:

addEventHandler in interface FormBehavior

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

Since:

1.0.2

getLink

protected ILink getLink(IRequestCycle cycle,
                        java.lang.String actionId)

Builds the EngineServiceLink for the form, using either the direct or action service.

Since:

1.0.3

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 java.lang.String getMethod()

method parameter

isStateful

public abstract boolean isStateful()

stateful parameter

Specified by:

isStateful in interface IDirect

getScheme

public abstract java.lang.String getScheme()

scheme parameter, may be null

getPort

public abstract java.lang.Integer getPort()

port , may be null

setEncodingType

public void setEncodingType(java.lang.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

See Also:

Upload

addHiddenValue

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

Since:

3.0

addHiddenValue

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

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

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

public void addDeferredRunnable(java.lang.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.