org.apache.cocoon.forms.formmodel
Class Form

java.lang.Object
  org.apache.cocoon.forms.formmodel.AbstractWidget
      org.apache.cocoon.forms.formmodel.AbstractContainerWidget
          org.apache.cocoon.forms.formmodel.Form

All Implemented Interfaces:

ContainerWidget, Widget, ValidationErrorAware, Locatable

public class Form
extends AbstractContainerWidget
implements ValidationErrorAware

A widget that serves as a container for other widgets, the top-level widget in a form description file.

Version:

$Id: Form.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Field Summary

static String

SUBMIT_ID_PARAMETER Form parameter containing the submit widget's id

Fields inherited from class org.apache.cocoon.forms.formmodel.AbstractContainerWidget

validationError, widgets

Fields inherited from class org.apache.cocoon.forms.formmodel.AbstractWidget

wasValid

Fields inherited from interface org.apache.cocoon.forms.formmodel.Widget

PATH_SEPARATOR

Constructor Summary

Form(FormDefinition definition)

Method Summary

void	addProcessingPhaseListener(ProcessingPhaseListener listener)
void	addWidgetEvent(WidgetEvent event) Events produced by child widgets should not be fired immediately, but queued in order to ensure an overall consistency of the widget tree before being handled.
boolean	addWidgetUpdate(Widget widget) Mark a widget as being updated.
void	endProcessing(boolean redisplayForm) End the current form processing after the current phase.
Set	getChildUpdatedWidgetIds()
WidgetDefinition	getDefinition() Concrete subclasses should allow access to their underlaying Definition through this method.
String	getId() Gets the id of this widget.
Locale	getLocale() Get the locale to be used to process this form.
Widget	getSubmitWidget() Get the widget that triggered the current processing.
Set	getUpdatedWidgetIds()
ValidationError	getValidationError() Set a validation error on this field.
String	getXMLElementName() The XML element name used in AbstractWidget.generateSaxFragment(ContentHandler, Locale) to produce the wrapping element for all the XML-instance-content of this Widget.
boolean	hasFormHandler()
void	informEndLoadingModel() Inform the form that the values are loaded.
void	informEndSavingModel() Inform the form that the values are saved.
void	informStartLoadingModel() Inform the form that the values will be loaded.
void	informStartSavingModel() Inform the form that the values will be saved.
void	initialize() Initialize the form by recursively initializing all its children.
boolean	isValid() Was form validation successful ?
boolean	process(FormContext formContext) Processes a form submit.
void	readFromRequest(FormContext formContext) Delegates the readFromRequest() down to the contained child-widgets.
void	removeProcessingPhaseListener(ProcessingPhaseListener listener)
void	setFormHandler(FormHandler formHandler)
void	setId(String value) Set the optional id.
void	setSubmitWidget(Widget widget) Set the widget that triggered the current form processing.
void	setValidationError(ValidationError error) set a validation error
boolean	validate() Performs validation phase of form processing.

Methods inherited from class org.apache.cocoon.forms.formmodel.AbstractContainerWidget

addChild, generateItemSaxFragment, getChild, getChildren, getSize, hasChild

Methods inherited from class org.apache.cocoon.forms.formmodel.AbstractWidget

addValidator, broadcastEvent, generateDisplayData, generateLabel, generateSaxFragment, getAttribute, getCombinedState, getForm, getFullName, getLocation, getName, getParent, getRequestParameterName, getState, getValue, getWidget, getXMLElementAttributes, isRequired, lookupWidget, removeAttribute, removeValidator, setAttribute, setParent, setState, setValue, toString, widgetNameChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.cocoon.forms.formmodel.Widget

addValidator, broadcastEvent, generateLabel, generateSaxFragment, getAttribute, getCombinedState, getForm, getFullName, getLocation, getName, getParent, getRequestParameterName, getState, getValue, getWidget, isRequired, lookupWidget, removeAttribute, removeValidator, setAttribute, setParent, setState, setValue

Field Detail

SUBMIT_ID_PARAMETER

public static final String SUBMIT_ID_PARAMETER

Form parameter containing the submit widget's id

See Also:

Constant Field Values

Constructor Detail

Form

public Form(FormDefinition definition)

Method Detail

initialize

public void initialize()

Initialize the form by recursively initializing all its children. Any events occuring within the initialization phase are buffered and fired after initialization is complete, so that any action from a widget on another one occurs after that other widget has been given the opportunity to initialize itself.

Specified by:

initialize in interface Widget

Overrides:

initialize in class AbstractContainerWidget

getDefinition

public WidgetDefinition getDefinition()

Description copied from class: AbstractWidget

Concrete subclasses should allow access to their underlaying Definition through this method. If subclasses decide to return null they should also organize own implementations of AbstractWidget.getId(), AbstractWidget.getLocation(), AbstractWidget.validate(), AbstractWidget.generateLabel(ContentHandler) and AbstractWidget.generateDisplayData(ContentHandler) to avoid NPE's.

Specified by:

getDefinition in interface Widget

Specified by:

getDefinition in class AbstractWidget

Returns:

the widgetDefinition from which this widget was instantiated. (See WidgetDefinition.createInstance())

addWidgetEvent

public void addWidgetEvent(WidgetEvent event)

Events produced by child widgets should not be fired immediately, but queued in order to ensure an overall consistency of the widget tree before being handled.

Parameters:

event - the event to queue

addWidgetUpdate

public boolean addWidgetUpdate(Widget widget)

Mark a widget as being updated. When it Ajax mode, only updated widgets will be redisplayed

Parameters:

widget - the updated widget

Returns:

true if this widget was added to the list (i.e. wasn't alredy marked for update)

getUpdatedWidgetIds

public Set getUpdatedWidgetIds()

getChildUpdatedWidgetIds

public Set getChildUpdatedWidgetIds()

informStartLoadingModel

public void informStartLoadingModel()

Inform the form that the values will be loaded.

informEndLoadingModel

public void informEndLoadingModel()

Inform the form that the values are loaded.

informStartSavingModel

public void informStartSavingModel()

Inform the form that the values will be saved.

informEndSavingModel

public void informEndSavingModel()

Inform the form that the values are saved.

getLocale

public Locale getLocale()

Get the locale to be used to process this form.

Returns:

the form's locale.

getSubmitWidget

public Widget getSubmitWidget()

Get the widget that triggered the current processing. Note that it can be any widget, and not necessarily an action or a submit.

Returns:

the widget that submitted this form.

setSubmitWidget

public void setSubmitWidget(Widget widget)

Set the widget that triggered the current form processing.

Parameters:

widget - the widget

hasFormHandler

public boolean hasFormHandler()

setFormHandler

public void setFormHandler(FormHandler formHandler)

addProcessingPhaseListener

public void addProcessingPhaseListener(ProcessingPhaseListener listener)

removeProcessingPhaseListener

public void removeProcessingPhaseListener(ProcessingPhaseListener listener)

process

public boolean process(FormContext formContext)

Processes a form submit. If the form is finished, i.e. the form should not be redisplayed to the user, then this method returns true, otherwise it returns false. To know if the form was sucessfully validated, use the isValid() method.

Form processing consists in multiple steps:

• all widgets read their value from the request (i.e. readFromRequest(FormContext) is called recursively on the whole widget tree)
• if there is an action event, call the FormHandler
• perform validation.

This processing can be interrupted by the widgets (or their event listeners) by calling endProcessing(boolean).

Note that this method is synchronized as a Form is not thread-safe. This should not be a bottleneck as such concurrent requests can only happen for a single user.

endProcessing

public void endProcessing(boolean redisplayForm)

End the current form processing after the current phase.

Parameters:

redisplayForm - indicates if the form should be redisplayed to the user.

isValid

public boolean isValid()

Was form validation successful ?

Specified by:

isValid in interface Widget

Overrides:

isValid in class AbstractWidget

Returns:

true if the form was successfully validated.

See Also:

Widget.isValid()

readFromRequest

public void readFromRequest(FormContext formContext)

Description copied from class: AbstractContainerWidget

Delegates the readFromRequest() down to the contained child-widgets. When overriding one should call super.readFromRequest() to allow child-widgets to process the request. Overide only to add possible request-reading statements on the containment level.

Specified by:

readFromRequest in interface Widget

Overrides:

readFromRequest in class AbstractContainerWidget

Parameters:

formContext - to be passed to the Widget.readFromRequest(FormContext) of the contained widgets.

getValidationError

public ValidationError getValidationError()

Set a validation error on this field. This allows the form to be externally marked as invalid by application logic.

Specified by:

getValidationError in interface ValidationErrorAware

Returns:

the validation error

setValidationError

public void setValidationError(ValidationError error)

set a validation error

Specified by:

setValidationError in interface ValidationErrorAware

validate

public boolean validate()

Performs validation phase of form processing.

Specified by:

validate in interface Widget

Overrides:

validate in class AbstractContainerWidget

Returns:

true only if all contained widgets are valid and the extra validation rules on this containment level are ok.

See Also:

Widget.validate()

getXMLElementName

public String getXMLElementName()

Description copied from class: AbstractWidget

The XML element name used in AbstractWidget.generateSaxFragment(ContentHandler, Locale) to produce the wrapping element for all the XML-instance-content of this Widget.

Specified by:

getXMLElementName in class AbstractWidget

Returns:

the main elementname for this widget's sax-fragment.

getId

public String getId()

Description copied from class: AbstractWidget

Gets the id of this widget.

Specified by:

getId in interface Widget

Overrides:

getId in class AbstractWidget

Returns:

the id of this widget. This should never be null Top-level container widgets (like 'form') should return ""

See Also:

AbstractWidget.getId()

setId

public void setId(String value)

Set the optional id.

Parameters:

value - A new id.