org.apache.tapestry
Interface IForm

All Superinterfaces:
IAction, IComponent, ILocatable, ILocationHolder, IRender
All Known Implementing Classes:
Form

public interface IForm
extends IAction

A generic way to access a component which defines an HTML form. This interface exists so that the IRequestCycle can invoke the rewind(IMarkupWriter, IRequestCycle) method (which is used to deal with a Form that uses the direct service). In release 1.0.5, more responsibility for forms was moved here.

Since:
1.0.2
Version:
$Id: IForm.java,v 1.7 2004/01/19 21:32:10 hlship Exp $
Author:
Howard Lewis Ship

Field Summary
static String ATTRIBUTE_NAME
          Attribute name used with the request cycle; allows other components to locate the IForm.
 
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.
 IValidationDelegate getDelegate()
          Returns the validation delegate for the form.
 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.
 String getName()
          Returns the name of the form.
 boolean isRewinding()
          Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).
 void rewind(IMarkupWriter writer, IRequestCycle cycle)
          Invoked by the IRequestCycle to allow a form that uses the direct service, to respond to the form submission.
 void setEncodingType(String encodingType)
          May be invoked by a component to force the encoding type of the form to a particular value.
 
Methods inherited from interface org.apache.tapestry.IAction
getRequiresSession
 
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
 

Field Detail

ATTRIBUTE_NAME

public static final String ATTRIBUTE_NAME
Attribute name used with the request cycle; allows other components to locate the IForm.

Since:
1.0.5
See Also:
Constant Field Values
Method Detail

rewind

public void rewind(IMarkupWriter writer,
                   IRequestCycle cycle)
Invoked by the IRequestCycle to allow a form that uses the direct service, to respond to the form submission.


addEventHandler

public void addEventHandler(FormEventType type,
                            String functionName)
Adds an additional event handler. The type determines when the handler will be invoked, FormEventType.SUBMIT is most typical.

Since:
1.0.5

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

Since:
1.0.5

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.

Invokes IFormComponent.setName(String) with the result, as well as returning it.

Throws:
StaleLinkException - if, when the form itself is rewinding, the element id allocated does not match the expected id (as allocated when the form rendered). This indicates that the state of the application has changed between the time the form renderred and the time it was submitted.
Since:
1.0.5

getName

public String getName()
Returns the name of the form.

Since:
1.0.5

isRewinding

public boolean isRewinding()
Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).

Since:
1.0.5

getDelegate

public IValidationDelegate getDelegate()
Returns the validation delegate for the form. Returns null if the form does not have a delegate.

Since:
1.0.8

setEncodingType

public void setEncodingType(String encodingType)
May be invoked by a component to force the encoding type of the form to a particular value.

Throws:
ApplicationRuntimeException - if the current encoding type is not null and doesn't match the suggested encoding type
Since:
3.0
See Also:
Upload

addHiddenValue

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

Since:
3.0