public abstract class Form extends AbstractComponent implements IForm, IDirect
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).
ATTRIBUTE_NAME
Constructor and Description |
---|
Form() |
Modifier and Type | Method and Description |
---|---|
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
FormBehavior.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.
|
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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getFocus, isClientValidationEnabled
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
public Form()
public static IForm get(IRequestCycle cycle)
TapestryUtils.getForm(IRequestCycle, IComponent)
instead.public boolean isRewinding()
isRewinding
in interface FormBehavior
org.apache.hivemind.ApplicationRuntimeException
- if not rendering.public abstract IEngineService getDirectService()
public abstract IEngineService getActionService()
public abstract boolean isDirect()
This is derived from the direct parameter, and defaults to true if not bound.
public boolean getRequiresSession()
getRequiresSession
in interface IAction
public java.lang.String getElementId(IFormComponent component)
Simply invokes
getElementId(org.apache.tapestry.form.IFormComponent, java.lang.String)
with the
component's id.
getElementId
in interface FormBehavior
public java.lang.String getElementId(IFormComponent component, java.lang.String baseId)
This method is provided simply so that some components (ImageSubmit
) have more
specific control over their names.
getElementId
in interface FormBehavior
public java.lang.String getName()
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.
getName
in interface IForm
AbstractFormComponent.getName()
protected void prepareForRender(IRequestCycle cycle)
AbstractComponent
AbstractComponent.render(IMarkupWriter, IRequestCycle)
to prepare the component to render.
This implementation sets JavaBeans properties from matching bound parameters. This
implementation does nothing.prepareForRender
in class AbstractComponent
protected void cleanupAfterRender(IRequestCycle cycle)
AbstractComponent
AbstractComponent.render(IMarkupWriter, IRequestCycle)
after the component renders. This
implementation does nothing.cleanupAfterRender
in class AbstractComponent
protected void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
AbstractComponent
AbstractComponent.render(IMarkupWriter, IRequestCycle)
to actually render the component
(with any parameter values already set). This is the method that subclasses must implement.renderComponent
in class AbstractComponent
protected java.lang.String constructFormNameForActionService(java.lang.String actionId)
protected FormSupport newFormSupport(IMarkupWriter writer, IRequestCycle cycle)
FormSupportImpl
.public void addEventHandler(FormEventType type, java.lang.String functionName)
addEventHandler
in interface FormBehavior
public void rewind(IMarkupWriter writer, IRequestCycle cycle)
AbstractComponent.render(IMarkupWriter, IRequestCycle)
.public void trigger(IRequestCycle cycle)
protected ILink getLink(IRequestCycle cycle, java.lang.String actionId)
public abstract WebResponse getResponse()
public abstract IValidationDelegate getDelegate()
getDelegate
in interface IForm
public abstract IActionListener getListener()
public abstract IActionListener getSuccess()
public abstract IActionListener getCancel()
public abstract IActionListener getRefresh()
public abstract java.lang.String getMethod()
public abstract boolean isStateful()
isStateful
in interface IDirect
public abstract java.lang.String getScheme()
public abstract java.lang.Integer getPort()
public void setEncodingType(java.lang.String encodingType)
FormBehavior
setEncodingType
in interface FormBehavior
Upload
public void addHiddenValue(java.lang.String name, java.lang.String value)
FormBehavior
It is acceptible to add multiple hidden fields with the same name. They will be written in the order they are received.
addHiddenValue
in interface FormBehavior
public void addHiddenValue(java.lang.String name, java.lang.String id, java.lang.String value)
FormBehavior
It is acceptible to add multiple hidden fields with the same name. They will be written in the order they are received.
addHiddenValue
in interface FormBehavior
public void prerenderField(IMarkupWriter writer, IComponent field, org.apache.hivemind.Location location)
FormBehavior
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.prerenderField
in interface FormBehavior
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.public boolean wasPrerendered(IMarkupWriter writer, IComponent field)
FormBehavior
wasPrerendered
in interface FormBehavior
public void addDeferredRunnable(java.lang.Runnable runnable)
FormBehavior
addDeferredRunnable
in interface FormBehavior
runnable
- the object to execute (which may not be null)public abstract ListenerInvoker getListenerInvoker()
public void registerForFocus(IFormComponent field, int priority)
FormBehavior
registerForFocus
in interface FormBehavior
field
- the field requesting focuspriority
- a priority level used to determine whether the registered field becomes the focus
field. Constants for this purpose are defined in ValidationConstants
.