Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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, 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.java 587759 2007-10-24 03:00:37Z vgritsenko $

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:

  - 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.

### 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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