com.primix.tapestry.form
Class Form

java.lang.Object
  |
  +--com.primix.tapestry.AbstractComponent
        |
        +--com.primix.tapestry.form.Form
All Implemented Interfaces:
IAction, IComponent, IDirect, IForm, IRender

public class Form
extends AbstractComponent
implements IForm, IDirect

Component which contains form element components. Forms use the action service to handle the form submission. A Form will wrap other components and static HTML, including form components such as Text, TextField, Checkbox, etc.

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.

The listener is always type IActionListener, even when the direct service is used.
Parameter Type Read / Write Required Default Description
method java.lang.String R no post The value to use for the method attribute of the <form> tag.
listener IActionListener R yes   The listener, informed after the wrapped components of the form have had a chance to absorb the request.
stateful boolean R no true If true (the default), then the component requires an active (i.e., non-new) HttpSession when triggered. Failing that, it throws a StaleLinkException. If false, then no check is necessary. Generally, forms are stateful, but it is possible to put a stateless form onto the Home page of an application.
direct boolean R no true If true (the default), then the direct service is used for the form. This decreases the amount of work required to process the form submission, and is acceptible for most forms, even those that contain Foreaches (but not those that are inside a Foreach.

An abbreviated form of the rewind cycle takes place, that only references the form and the components it wraps.

Informal parameters are allowed.

Version:
$Id: Form.java,v 1.18 2001/08/28 20:33:41 hship Exp $
Author:
Howard Ship

Fields inherited from class com.primix.tapestry.AbstractComponent
id, page, specification, wrapped, wrappedCount
 
Fields inherited from interface com.primix.tapestry.IForm
ATTRIBUTE_NAME
 
Constructor Summary
Form()
           
 
Method Summary
 void addEventHandler(FormEventType type, java.lang.String functionName)
          Adds an additional event handler.
static IForm get(IRequestCycle cycle)
          Returns the currently active IForm, or null if no form is active.
 IBinding getDirectBinding()
           
 java.lang.String getElementId(IComponent component)
          Constructs a unique identifier (within the Form).
 java.lang.String getElementId(java.lang.String baseId)
          Constructs a unique identifier from the base id.
 IBinding getListenerBinding()
           
 IBinding getMethodBinding()
           
 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.
 IBinding getStatefulBinding()
           
 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.
 void render(IResponseWriter writer, IRequestCycle cycle)
          The principal rendering/rewinding method.
 void rewind(IResponseWriter writer, IRequestCycle cycle)
          Simply invokes render(IResponseWriter, IRequestCycle).
 void setDirectBinding(IBinding value)
           
 void setListenerBinding(IBinding value)
           
 void setMethodBinding(IBinding value)
           
 void setStatefulBinding(IBinding value)
           
 void trigger(IRequestCycle cycle, java.lang.String[] context)
          Method invoked by the direct service.
 
Methods inherited from class com.primix.tapestry.AbstractComponent
addAsset, addComponent, addWrapped, cleanupAfterRender, cleanupComponent, finishLoad, finishLoad, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, generateAttributes, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getChangeObserver, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getListeners, getPage, getSpecification, prepareForRender, renderWrapped, reset, setBinding, setContainer, setId, setPage, setSpecification, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.primix.tapestry.IComponent
addAsset, addComponent, addWrapped, finishLoad, getAsset, getAssets, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getPage, getSpecification, renderWrapped, setBinding, setContainer, setId, setPage, setSpecification
 

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.

getMethodBinding

public IBinding getMethodBinding()

setListenerBinding

public void setListenerBinding(IBinding value)

getListenerBinding

public IBinding getListenerBinding()

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:
RenderOnlyPropertyException - if not rendering.

setStatefulBinding

public void setStatefulBinding(IBinding value)

getStatefulBinding

public IBinding getStatefulBinding()

getDirectBinding

public IBinding getDirectBinding()
Since:
1.0.2

setDirectBinding

public void setDirectBinding(IBinding value)
Since:
1.0.2

isDirect

public 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(IComponent 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(String) with the component's id.

Specified by:
getElementId in interface IForm
Since:
1.0.2

getElementId

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

render

public void render(IResponseWriter writer,
                   IRequestCycle cycle)
            throws RequestCycleException
Description copied from interface: IRender
The principal rendering/rewinding method. This will cause the receiving component to render its top level elements (HTML text and components).

Renderring and rewinding are the exact same process. The same code that renders must be able to restore state by going through the exact same operations (even though the output is discarded).

Specified by:
render in interface IRender

setMethodBinding

public void setMethodBinding(IBinding value)

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

rewind

public void rewind(IResponseWriter writer,
                   IRequestCycle cycle)
            throws RequestCycleException
Simply invokes render(IResponseWriter, IRequestCycle).
Specified by:
rewind in interface IForm
Since:
1.0.2

trigger

public void trigger(IRequestCycle cycle,
                    java.lang.String[] context)
             throws RequestCycleException
Method invoked by the direct service.
Specified by:
trigger in interface IDirect
Since:
1.0.2