org.apache.tapestry.form
Class FormSupportImpl

java.lang.Object
  extended by org.apache.tapestry.form.FormSupportImpl
All Implemented Interfaces:
FormSupport, FormBehavior
Direct Known Subclasses:
GoFormSupportImpl

public class FormSupportImpl
extends java.lang.Object
implements FormSupport

Encapsulates most of the behavior of a Form component.

Since:
4.0
Author:
Howard M. Lewis Ship

Field Summary
static java.lang.String FIELD_FOCUS_ATTRIBUTE
          Attribute set to true when a field has been focused; used to prevent conflicting JavaScript for field focusing from being emitted.
static java.lang.String FORM_IDS
          Name of query parameter storing the ids alloocated while rendering the form, as a comma seperated list.
static java.lang.String RESERVED_FORM_IDS
          Names of additional ids that were pre-reserved, as a comma-sepereated list.
static java.lang.String SCRIPT
           
static java.lang.String SUBMIT_MODE
          Indicates why the form was submitted: whether for normal ("submit"), refresh, or because the form was canceled.
 
Constructor Summary
FormSupportImpl(IMarkupWriter writer, IRequestCycle cycle, IForm 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 event handler for the form, of the given type.
 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 emitEventManagerInitialization(java.lang.String formId)
          Pre-renders the form, setting up some client-side form support.
 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 (within the Form).
 boolean isRewinding()
          Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).
 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.
 void render(java.lang.String method, IRender informalParametersRenderer, ILink link, java.lang.String scheme)
          Deprecated. Please use second render method.
 void render(java.lang.String method, IRender informalParametersRenderer, ILink link, java.lang.String scheme, java.lang.Integer port)
          Invoked when the form is rendering.
 java.lang.String rewind()
          Invoked to rewind the form, which renders the body of the form, allowing form element components to pull data from the request and update page properties.
 void setEncodingType(java.lang.String encodingType)
          May be invoked by a component to force the encoding type of the form to a particular value.
 boolean wasPrerendered(IMarkupWriter writer, IComponent field)
          Invoked by a form control component (a field) that may have been pre-rendered.
protected  void writeHiddenField(IMarkupWriter writer, java.lang.String name, java.lang.String id, java.lang.String value)
          Overwridden by GoFormSupportImpl (WML).
protected  void writeHiddenFieldList()
          Writes out all hidden values previously added by addHiddenValue(String, String, String), plus the allocated id list.
protected  void writeHiddenFields()
          Writes out all hidden values previously added by addHiddenValue(String, String, String).
protected  void writeTag(IMarkupWriter writer, java.lang.String method, java.lang.String url)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FORM_IDS

public static final java.lang.String FORM_IDS
Name of query parameter storing the ids alloocated while rendering the form, as a comma seperated list. This information is used when the form is submitted, to ensure that the rewind allocates the exact same sequence of ids.

See Also:
Constant Field Values

RESERVED_FORM_IDS

public static final java.lang.String RESERVED_FORM_IDS
Names of additional ids that were pre-reserved, as a comma-sepereated list. These are names beyond that standard set. Certain engine services include extra parameter values that must be accounted for, and page properties may be encoded as additional query parameters.

See Also:
Constant Field Values

SUBMIT_MODE

public static final java.lang.String SUBMIT_MODE
Indicates why the form was submitted: whether for normal ("submit"), refresh, or because the form was canceled.

See Also:
Constant Field Values

SCRIPT

public static final java.lang.String SCRIPT
See Also:
Constant Field Values

FIELD_FOCUS_ATTRIBUTE

public static final java.lang.String FIELD_FOCUS_ATTRIBUTE
Attribute set to true when a field has been focused; used to prevent conflicting JavaScript for field focusing from being emitted.

See Also:
Constant Field Values
Constructor Detail

FormSupportImpl

public FormSupportImpl(IMarkupWriter writer,
                       IRequestCycle cycle,
                       IForm form)
Method Detail

addEventHandler

public void addEventHandler(FormEventType type,
                            java.lang.String functionName)
Adds an event handler for the form, of the given type.

Specified by:
addEventHandler in interface FormBehavior

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

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

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

getElementId

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

isRewinding

public boolean isRewinding()
Description copied from interface: FormBehavior
Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).

Specified by:
isRewinding in interface FormBehavior

render

public void render(java.lang.String method,
                   IRender informalParametersRenderer,
                   ILink link,
                   java.lang.String scheme)
Deprecated. Please use second render method.

Description copied from interface: FormSupport
Old interface left around for backwards compatibility. Please use the second render method.

Specified by:
render in interface FormSupport
Parameters:
method - the HTTP method ("get" or "post")
informalParametersRenderer - object that will render informal parameters
link - The link to which the form will submit (encapsulating the URL and the query parameters)
scheme - the desired scheme for the generated URL, typically "http" or "https". If non-null, and the scheme does not match the current request's scheme, then an absolute URL with the specified scheme will be generated, rather than a URI.

render

public void render(java.lang.String method,
                   IRender informalParametersRenderer,
                   ILink link,
                   java.lang.String scheme,
                   java.lang.Integer port)
Description copied from interface: FormSupport
Invoked when the form is rendering. This should only be invoked by the Form component.

Specified by:
render in interface FormSupport
Parameters:
method - the HTTP method ("get" or "post")
informalParametersRenderer - object that will render informal parameters
link - The link to which the form will submit (encapsulating the URL and the query parameters)
scheme - the desired scheme for the generated URL, typically "http" or "https". If non-null, and the scheme does not match the current request's scheme, then an absolute URL with the specified scheme will be generated, rather than a URI.
port - the desired port for the generated URL, typically "80", "443". If non-null, and the port does not match the current request's port, then an absolute URL with the specified port will be generated, rather than a URI.

emitEventManagerInitialization

protected void emitEventManagerInitialization(java.lang.String formId)
Pre-renders the form, setting up some client-side form support. Returns the name of the client-side form event manager variable.


rewind

public java.lang.String rewind()
Description copied from interface: FormSupport
Invoked to rewind the form, which renders the body of the form, allowing form element components to pull data from the request and update page properties. This should only be invoked by the Form component.

Specified by:
rewind in interface FormSupport
Returns:
a code indicating why the form was submitted: FormConstants.SUBMIT_NORMAL, FormConstants.SUBMIT_CANCEL or FormConstants.SUBMIT_REFRESH.

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

writeHiddenField

protected void writeHiddenField(IMarkupWriter writer,
                                java.lang.String name,
                                java.lang.String id,
                                java.lang.String value)
Overwridden by GoFormSupportImpl (WML).


writeHiddenFields

protected void writeHiddenFields()
Writes out all hidden values previously added by addHiddenValue(String, String, String). Writes a <div> tag around writeHiddenFieldList(). Overriden by GoFormSupportImpl.


writeHiddenFieldList

protected void writeHiddenFieldList()
Writes out all hidden values previously added by addHiddenValue(String, String, String), plus the allocated id list.


writeTag

protected void writeTag(IMarkupWriter writer,
                        java.lang.String method,
                        java.lang.String url)

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)

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.