org.apache.tapestry.form
Class Form

java.lang.Object
  org.apache.tapestry.spec.BaseLocatable
      org.apache.tapestry.AbstractComponent
          org.apache.tapestry.form.Form

All Implemented Interfaces:

IAction, IComponent, IDirect, IForm, ILocatable, ILocationHolder, 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.

Version:

$Id: Form.java 243805 2004-02-26 16:11:20Z tsvetelin $

Author:

Howard Lewis Ship, David Solis

Field Summary

Fields inherited from interface org.apache.tapestry.IForm

ATTRIBUTE_NAME

Constructor Summary

Form()

Method Summary

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 String	buildAllocatedIdList() Converts the allocateIds property into a string, a comma-separated list of ids.
protected void	cleanupAfterRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle) after the component renders, to clear any parameters back to null (or 0, or false, or whatever the correct default is).
protected void	emitEventHandlers(IMarkupWriter writer, IRequestCycle cycle)
protected void	finishLoad() Invoked, as a convienience, from AbstractComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).
static IForm	get(IRequestCycle cycle) Returns the currently active IForm, or null if no form is active.
abstract IValidationDelegate	getDelegate() Returns the validation delegate for the form.
protected String	getDisplayName() Returns the name of the element.
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 IActionListener	getListener()
abstract String	getMethod()
String	getName() Returns the name generated for the form.
boolean	getRequiresSession() Returns true if the stateful parameter is bound to a true value.
abstract IBinding	getStatefulBinding()
protected String	getTag() Returns the tag of the form.
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.
boolean	isStateful() Invoked when not rendering, so it uses the stateful binding.
protected void	prepareForRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle) to prepare the component to render.
protected void	reconstructAllocatedIds(String storedIdList) Converts a string passed as a parameter (and containing a comma separated list of ids) back into the allocateIds property.
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).
abstract void	setDelegate(IValidationDelegate delegate)
abstract void	setDirect(boolean direct)
void	setEncodingType(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.
protected void	writeAttributes(IMarkupWriter writer, ILink link)
protected void	writeHiddenField(IMarkupWriter writer, String name, String value)
protected void	writeHiddenField(IMarkupWriter writer, String name, String id, String value)
protected void	writeHiddenValues(IMarkupWriter writer) Writes hidden values accumulated during the render (by components invoking addHiddenValue(String, String).

Methods inherited from class org.apache.tapestry.AbstractComponent

addAsset, addBody, addComponent, finishLoad, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, format, format, format, format, formatString, formatString, formatString, formatString, generateAttributes, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getBody, getBodyCount, getChangeObserver, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getListeners, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, getString, pageEndRender, render, renderBody, renderInformalParameters, setBinding, setContainer, setId, setNamespace, setPage, setProperty, setSpecification, toString

Methods inherited from class org.apache.tapestry.spec.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.IComponent

addAsset, addBody, addComponent, finishLoad, getAsset, getAssets, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, getString, renderBody, setBinding, setContainer, setId, setNamespace, setPage, setProperty, setSpecification

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.tapestry.ILocationHolder

setLocation

Methods inherited from interface org.apache.tapestry.ILocatable

getLocation

Constructor Detail

Form

public Form()

Method Detail

get

public static IForm get(IRequestCycle cycle)

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 IForm

Throws:

ApplicationRuntimeException - if not rendering.

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 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 IForm

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 IForm

Since:

1.0.3

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 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. Subclasses that override this method must invoke this implementation as well.

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, to clear any parameters back to null (or 0, or false, or whatever the correct default is). Primarily, this is used to ensure that the component doesn't hold onto any objects that could otherwise be garbage collected.

Subclasses may override this implementation, but must also invoke it.

Overrides:

cleanupAfterRender in class AbstractComponent

writeAttributes

protected void writeAttributes(IMarkupWriter writer,
                               ILink link)

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

addEventHandler

public void addEventHandler(FormEventType type,
                            String functionName)

Adds an additional event handler.

Specified by:

addEventHandler in interface IForm

Since:

1.0.2

emitEventHandlers

protected void emitEventHandlers(IMarkupWriter writer,
                                 IRequestCycle cycle)

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

writeHiddenField

protected void writeHiddenField(IMarkupWriter writer,
                                String name,
                                String value)

Since:

3.0

writeHiddenField

protected void writeHiddenField(IMarkupWriter writer,
                                String name,
                                String id,
                                String value)

buildAllocatedIdList

protected String buildAllocatedIdList()

Converts the allocateIds property into a string, a comma-separated list of ids. This is included as a hidden field in the form and is used to identify discrepencies when the form is submitted.

Since:

3.0

reconstructAllocatedIds

protected void reconstructAllocatedIds(String storedIdList)

Converts a string passed as a parameter (and containing a comma separated list of ids) back into the allocateIds property.

Since:

3.0

See Also:

buildAllocatedIdList()

getDelegate

public abstract IValidationDelegate getDelegate()

Description copied from interface: IForm

Returns the validation delegate for the form. Returns null if the form does not have a delegate.

Specified by:

getDelegate in interface IForm

setDelegate

public abstract void setDelegate(IValidationDelegate delegate)

setDirect

public abstract void setDirect(boolean direct)

getListener

public abstract IActionListener getListener()

getMethod

public abstract String getMethod()

isStateful

public boolean isStateful()

Invoked when not rendering, so it uses the stateful binding. If not bound, returns true.

Specified by:

isStateful in interface IDirect

getStatefulBinding

public abstract IBinding getStatefulBinding()

finishLoad

protected void finishLoad()

Description copied from class: AbstractComponent

Invoked, as a convienience, from AbstractComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification). This implemenation does nothing. Subclasses may override without invoking this implementation.

Overrides:

finishLoad in class AbstractComponent

setEncodingType

public void setEncodingType(String encodingType)

Description copied from interface: IForm

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

Specified by:

setEncodingType in interface IForm

See Also:

Upload

getTag

protected String getTag()

Returns the tag of the form.

Since:

3.0

getDisplayName

protected String getDisplayName()

Returns the name of the element.

Since:

3.0

addHiddenValue

public void addHiddenValue(String name,
                           String value)

Description copied from interface: IForm

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 IForm

Since:

3.0

addHiddenValue

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

Description copied from interface: IForm

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 IForm

Since:

3.0

writeHiddenValues

protected void writeHiddenValues(IMarkupWriter writer)

Writes hidden values accumulated during the render (by components invoking addHiddenValue(String, String).

Since:

3.0