org.apache.tapestry.form
Class Form

java.lang.Object
  extended byorg.apache.hivemind.impl.BaseLocatable
      extended byorg.apache.tapestry.AbstractComponent
          extended byorg.apache.tapestry.form.Form
All Implemented Interfaces:
FormBehavior, 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.

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