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:
IAction, IComponent, IDirect, IForm, IRender, org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder
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.

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, 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  java.lang.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.
protected  void emitEventHandlers(IMarkupWriter writer, IRequestCycle cycle)
           
static IForm get(IRequestCycle cycle)
          Returns the currently active IForm, or null if no form is active.
abstract  IEngineService getActionService()
          Injected.
abstract  IValidationDelegate getDelegate()
          Returns the validation delegate for the form.
abstract  IEngineService getDirectService()
          Injected.
protected  java.lang.String getDisplayName()
          Returns the name of the element.
 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.
abstract  IActionListener getListener()
           
abstract  java.lang.String getMethod()
           
 java.lang.String getName()
          Returns the name generated for the form.
 boolean getRequiresSession()
          Returns true if the stateful parameter is bound to a true value.
protected  java.lang.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.
abstract  boolean isStateful()
          Invoked by the direct service to query the component as to whether it is stateful.
protected  void prepareForRender(IRequestCycle cycle)
          Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)to prepare the component to render.
protected  void reconstructAllocatedIds(IRequestCycle cycle)
          Invoked when rewinding a form to re-initialize the _allocatedIds and _elementIdAllocator.
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)
           
 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.
protected  void writeAttributes(IMarkupWriter writer, ILink link)
           
protected  void writeHiddenField(IMarkupWriter writer, java.lang.String name, java.lang.String value)
           
protected  void writeHiddenField(IMarkupWriter writer, java.lang.String name, java.lang.String id, java.lang.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, checkActiveLock, enterActiveState, finishLoad, finishLoad, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getBody, getBodyCount, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getListeners, getNamespace, getPage, getProperty, isInActiveState, isParameterBound, isRendering, pageEndRender, render, renderBody, renderInformalParameters, setBinding, 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.IComponent
addAsset, addBody, addComponent, enterActiveState, finishLoad, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getListeners, getMessages, getNamespace, getPage, getProperty, getSpecification, isRendering, renderBody, setBinding, 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)
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:
org.apache.hivemind.ApplicationRuntimeException - if not rendering.

getDirectService

public abstract IEngineService getDirectService()
Injected.

Since:
3.1

getActionService

public abstract IEngineService getActionService()
Injected.

Since:
3.1

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

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,
                            java.lang.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,
                                java.lang.String name,
                                java.lang.String value)
Since:
3.0

writeHiddenField

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

buildAllocatedIdList

protected java.lang.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(IRequestCycle cycle)
Invoked when rewinding a form to re-initialize the _allocatedIds and _elementIdAllocator. Converts a string passed as a parameter (and containing a comma separated list of ids) back into the allocateIds property. In addition, return the state of the ID allocater back to where it was at the start of the render.

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)

getListener

public abstract IActionListener getListener()

getMethod

public abstract java.lang.String getMethod()

isStateful

public abstract boolean isStateful()
Description copied from interface: IDirect
Invoked by the direct service to query the component as to whether it is stateful. If stateful and no HttpSession is active, then a StaleSessionException is thrown by the service.

Specified by:
isStateful in interface IDirect

setEncodingType

public void setEncodingType(java.lang.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 java.lang.String getTag()
Returns the tag of the form. The WML equivalent, Go, overrides this.

Since:
3.0

getDisplayName

protected java.lang.String getDisplayName()
Returns the name of the element. The WML equivalent, Go, overrides this.

Since:
3.0

addHiddenValue

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