org.apache.cocoon.forms.formmodel
Class Form

java.lang.Object
  extended byorg.apache.cocoon.forms.formmodel.AbstractWidget
      extended byorg.apache.cocoon.forms.formmodel.AbstractContainerWidget
          extended byorg.apache.cocoon.forms.formmodel.Form
All Implemented Interfaces:
ContainerWidget, org.apache.cocoon.util.location.Locatable, ValidationErrorAware, Widget

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 1304280 2012-03-23 11:18:01Z 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()
          Get this widget's definition.
 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 interface: Widget
Get this widget's definition.

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:

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.

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
See Also:
AbstractWidget.getId()

setId

public void setId(String value)
Set the optional id.

Parameters:
value - A new id.


Copyright 1999-2008 The Apache Software Foundation. All Rights Reserved.