org.apache.tapestry.form
Class FormSupportImpl

java.lang.Object
  org.apache.tapestry.form.FormSupportImpl

All Implemented Interfaces:

FormSupport, FormBehavior

Direct Known Subclasses:

GoFormSupportImpl

public class FormSupportImpl
extends Object
implements FormSupport

Encapsulates most of the behavior of a Form component.

Field Summary

protected IRequestCycle	_cycle
static 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 String	FORM_IDS Name of query parameter storing the ids alloocated while rendering the form, as a comma seperated list.
static String	RESERVED_FORM_IDS Names of additional ids that were pre-reserved, as a comma-sepereated list.
static String	SEED_IDS DataSqueezer squeezed list of IRequestCycle id allocation state as it was just before this form was rendered.
static 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)

FormSupportImpl(IMarkupWriter writer, IRequestCycle cycle, IForm form, JavascriptManager javascriptManager)

Method Summary

void	addDeferredRunnable(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, String functionName) Adds an additional event handler.
void	addHiddenValue(String name, String value) Adds a hidden field value to be stored in the form.
void	addHiddenValue(String name, String id, String value) Adds a hidden field value to be stored in the form.
protected void	emitEventManagerInitialization(String formId) Pre-renders the form, setting up some client-side form support.
String	getElementId(IFormComponent component) Constructs a unique identifier (within the Form).
String	getElementId(IFormComponent component, String baseId) Constructs a unique identifier (within the Form).
IForm	getForm() Gets a reference to the previously stored IForm.
protected IMarkupWriter	getHiddenFieldWriter() Determines if a hidden field change has occurred, which would require that we write hidden form fields using the ResponseBuilder writer.
JSONObject	getProfile() The javascript object profile being built by this context to validate/translate form values.
boolean	isFormFieldUpdating() Checks to see if a form field has been updated.
boolean	isRewinding() Returns true if the form is rewinding (meaning, the form was the subject of the request cycle).
String	peekClientId(IFormComponent comp) Used internally to "peek" at what the next generated client id will be for the given component when it renders.
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(String method, IRender informalParametersRenderer, ILink link, String scheme, Integer port) Invoked when the form is rendering.
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(String encodingType) May be invoked by a component to force the encoding type of the form to a particular value.
void	setFormFieldUpdating(boolean value) Sets a flag denoting whether or not an IFormComponent field has been updated according to the logic defined in ResponseBuilder.updateComponent(String).
boolean	wasPrerendered(IComponent field) Invoked to check if a particular component has been pre-rendered.
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, String name, String id, String value) Overwridden by GoFormSupportImpl (WML).
protected void	writeHiddenFieldList(IMarkupWriter writer) 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, String method, 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 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 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

SEED_IDS

public static final String SEED_IDS

DataSqueezer squeezed list of IRequestCycle id allocation state as it was just before this form was rendered. Is used to ensure that all generated form ids are globally unique and consistent between requests.

See Also:

Constant Field Values

SUBMIT_MODE

public static final 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

FIELD_FOCUS_ATTRIBUTE

public static final 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

_cycle

protected final IRequestCycle _cycle

Constructor Detail

FormSupportImpl

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

FormSupportImpl

public FormSupportImpl(IMarkupWriter writer,
                       IRequestCycle cycle,
                       IForm form,
                       JavascriptManager javascriptManager)

Method Detail

getForm

public IForm getForm()

Gets a reference to the previously stored IForm.

Specified by:

getForm in interface FormSupport

Returns:

The form this object is managing/supporting.

addEventHandler

public void addEventHandler(FormEventType type,
                            String functionName)

Adds an additional event handler. The type determines when the handler will be invoked, FormEventType.SUBMITis most typical.

Specified by:

addEventHandler in interface FormBehavior

Parameters:

type - Type of event to add.

functionName - Name of the javascript function being added.

addHiddenValue

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

Parameters:

name - The name of the hidden input.

value - The value to store in the hidden field.

addHiddenValue

public void addHiddenValue(String name,
                           String id,
                           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

Parameters:

name - The name of the hidden input.

id - The id of the hidden input - should almost always be the same as the name.

value - The value to store in the hidden field.

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(org.apache.tapestry.form.IFormComponent, java.lang.String)with the component's id.

Specified by:

getElementId in interface FormBehavior

Parameters:

component - The component to get the unique id of.

Returns:

The unique id for this component, to be used in rendering name="id" type elements.

getElementId

public String getElementId(IFormComponent component,
                           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

Parameters:

component - The component to generate an element id for.

baseId - The basic id of the component.

Returns:

The form specific unique identifier for the given element. May be the same as the baseId if this is the first render of that specific component.

peekClientId

public String peekClientId(IFormComponent comp)

Description copied from interface: FormBehavior

Used internally to "peek" at what the next generated client id will be for the given component when it renders. Similar to the logic found in IRequestCycle.peekUniqueId(String).

Specified by:

peekClientId in interface FormBehavior

Parameters:

comp - The component to determine the next client id for.

Returns:

The next possible client ID for the component.

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

Returns:

True if the form is rewinding, false otherwise.

render

public void render(String method,
                   IRender informalParametersRenderer,
                   ILink link,
                   String scheme,
                   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(String formId)

Pre-renders the form, setting up some client-side form support. Returns the name of the client-side form event manager variable.

Parameters:

formId - The client id of the form.

rewind

public 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(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

Parameters:

encodingType - The encoding type to set.

See Also:

Upload

writeHiddenField

protected void writeHiddenField(IMarkupWriter writer,
                                String name,
                                String id,
                                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(IMarkupWriter). Overriden by GoFormSupportImpl.

writeHiddenFieldList

protected void writeHiddenFieldList(IMarkupWriter writer)

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

getHiddenFieldWriter

protected IMarkupWriter getHiddenFieldWriter()

Determines if a hidden field change has occurred, which would require that we write hidden form fields using the ResponseBuilder writer.

Returns:

The default IMarkupWriter if not doing a managed ajax/json response, else whatever is returned from ResponseBuilder.

writeTag

protected void writeTag(IMarkupWriter writer,
                        String method,
                        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

Parameters:

writer - The markup writer to render with. (may be ignored during dynamic requests)

field - The component to check for pre-rendering.

Returns:

true if the field was pre-rendered and should do nothing during its render phase, false if the field should continue as normal.

wasPrerendered

public boolean wasPrerendered(IComponent field)

Description copied from interface: FormBehavior

Invoked to check if a particular component has been pre-rendered.

Specified by:

wasPrerendered in interface FormBehavior

Parameters:

field - The component to check for pre-rendering. (Such as is done by FieldLabel.

Returns:

True if the component was pre-rendered, false otherwise.

addDeferredRunnable

public void addDeferredRunnable(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.

getProfile

public JSONObject getProfile()

The javascript object profile being built by this context to validate/translate form values.

Specified by:

getProfile in interface FormBehavior

Returns:

JSONObject profile.

isFormFieldUpdating

public boolean isFormFieldUpdating()

Checks to see if a form field has been updated.

Specified by:

isFormFieldUpdating in interface FormBehavior

Returns:

True if any form field was updated.

See Also:

FormBehavior.setFormFieldUpdating(boolean)

setFormFieldUpdating

public void setFormFieldUpdating(boolean value)

Sets a flag denoting whether or not an IFormComponent field has been updated according to the logic defined in ResponseBuilder.updateComponent(String).

Currently this flag is used during ajax/json responses so that cooperating ResponseBuilders can be worked with to ensure form state is properly updated on the client. Specifically, that the hidden form input fields and any associated validation profiles are updated.

Specified by:

setFormFieldUpdating in interface FormBehavior

Parameters:

value - The value to set.