com.arsdigita.bebop
Class FormSection

java.lang.Object
  extended bycom.arsdigita.bebop.Completable
      extended bycom.arsdigita.bebop.SimpleComponent
          extended bycom.arsdigita.bebop.FormSection
All Implemented Interfaces:
Cloneable, Component, Container, Lockable
Direct Known Subclasses:
DemoDispatcher.DeliverySection, Form, FormStep, OptionEditor, ResourceConfigFormSection, SaveCancelSection, SearchAndSelect, TextEntryFormSection, YesNoSection, YesNoSection

public class FormSection
extends SimpleComponent
implements Container

A standalone section of a Form. A FormSection contains other Bebop components, most importantly Widgets and associated listeners. It serves two purposes:

Since a FormSection has its own init, validation, and process listeners, it can do all of its processing without any intervention from the enclosing form. Although a FormSection contains all the same pieces that a Form does, it can only be used if it is added directly or indirectly to a Form. FormSections that are not contained in a Form do not exhibit any useful behavior.

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/FormSection.java#13 $
Author:
Karl Goldstein, Uday Mathur, Stas Freidin, Rory Solomon, David Lutterkort
See Also:
Form, FormModel

Field Summary
protected  FormModel m_formModel
          Underlying FormModel that stores the parameter models for all the widgets in this form section.
protected  Container m_panel
          The container to which all children are added.
static String versionId
           
 
Fields inherited from class com.arsdigita.bebop.SimpleComponent
m_attr
 
Fields inherited from interface com.arsdigita.bebop.Component
BEBOP_XML_NS, CLASS, ID, ON_CLICK, STYLE
 
Constructor Summary
  FormSection()
          Constructs a new form section.
  FormSection(Container panel)
          Constructs a new form section.
protected FormSection(Container panel, FormModel model)
          Constructs a new form section.
 
Method Summary
 void add(Component pc)
          Adds a component to this container.
 void add(Component pc, int constraints)
          Adds a component with the specified layout constraints to this container.
 void addCancelListener(FormCancelListener listener)
          Adds a listener for form cancellation events.
 void addInitListener(FormInitListener listener)
          Adds a listener for form initialization events.
 void addProcessListener(FormProcessListener listener)
          Adds a listener for form processing events.
 void addSubmissionListener(FormSubmissionListener listener)
          Adds a listener that is called as soon as the FormData has been initialized with the request parameters but before any of the init, validation, or process listeners are run.
 void addValidationListener(FormValidationListener listener)
          Adds a validation listener, implementing a custom validation check that applies to the form as a whole.
 Iterator children()
          Returns an iterator over the children of this component.
 boolean contains(Object o)
          Returns true if this list contains the specified element.
protected  FormInitListener createInitListener()
          Creates the init listener that forwards init events to this form section.
protected  FormProcessListener createProcessListener()
           
protected  FormSubmissionListener createSubmissionListener()
          Creates the submission listener that forwards submission events to this form section.
protected  FormValidationListener createValidationListener()
          Create the validation listener that forwards validation events to this form section.
protected  void fireCancel(FormSectionEvent e)
          Calls the cancel method on all registered cancellation listeners.
protected  void fireInit(FormSectionEvent e)
          Calls the init method on all registered init listeners.
protected  void fireProcess(FormSectionEvent e)
          Calls the process method on all registered process listeners.
protected  void fireSubmitted(FormSectionEvent e)
          Calls the submitted method on all registered submission listeners.
protected  void fireValidate(FormSectionEvent e)
          Calls the validate method on all registered validation listeners.
protected  void forwardInit()
           
protected  void forwardProcess()
           
protected  void forwardSubmission()
           
protected  void forwardValidation()
           
 void generateXML(PageState pageState, Element parent)
          Builds an XML subtree for this component under the specified parent.
 Component get(int index)
          Returns the Component at the specified position.
protected  FormModel getModel()
          Accessor method for this form's FormModel.
 Container getPanel()
          Returns the implicit Container of this FormSection.
 int indexOf(Component pc)
           
 boolean isEmpty()
          Determines whether the container contains any components.
 void lock()
          Locks this FormSection, its FormModel, and the implicit Container.
 FormData process(PageState data)
          Since a form section cannot be processed, always throws an error.
 void register(Form f, FormModel m)
          Traverses the children this FormSection, collecting parameter models and listeners into the supplied FormModel.
 void removeCancelListener(FormCancelListener listener)
          Removes the specified cancellation listener from the list of cancellation listeners (if it had previously been added).
 void removeInitListener(FormInitListener listener)
          Removes the specified init listener from the list of init listeners (if it had previously been added).
 void removeProcessListener(FormProcessListener listener)
          Removes the specified process listener from the list of process listeners (if it had previously been added).
 void removeSubmissionListener(FormSubmissionListener listener)
          Removes the specified submission listener from the list of submission listeners (if it had previously been added).
 void removeValidationListener(FormValidationListener listener)
          Removes the specified validation listener from the list of validation listeners (if it had previously been added).
 void respond(PageState state)
          Responds to the request.
 int size()
          Returns the number of elements in this container.
 
Methods inherited from class com.arsdigita.bebop.SimpleComponent
clone, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, register, setAttribute, setClassAttr, setIdAttr, setKey, setMetaDataAttribute, setStyleAttr, setVisible
 
Methods inherited from class com.arsdigita.bebop.Completable
addCompletionListener, fireCompletionEvent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.arsdigita.bebop.Component
getClassAttr, getIdAttr, getKey, getStyleAttr, isVisible, register, setClassAttr, setIdAttr, setKey, setStyleAttr, setVisible
 
Methods inherited from interface com.arsdigita.util.Lockable
isLocked
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

m_formModel

protected FormModel m_formModel
Underlying FormModel that stores the parameter models for all the widgets in this form section.


m_panel

protected Container m_panel
The container to which all children are added. A ColumnPanel by default.

Constructor Detail

FormSection

public FormSection()
Constructs a new form section. Sets the implicit layout Container of this FormSection to two column ColumnPanel by calling the 1-argument constructor.


FormSection

public FormSection(Container panel)
Constructs a new form section. Sets the form model of this FormSection to a new, anonymous FormModel.


FormSection

protected FormSection(Container panel,
                      FormModel model)
Constructs a new form section. Sets the implicit layout Container of this FormSection to panel. Sets the form model of this FormSection to model.

Parameters:
panel - the container within this form section that holds the components that are added to the form section with calls to the add methods
model - the form model for this form section
Method Detail

addSubmissionListener

public void addSubmissionListener(FormSubmissionListener listener)
Adds a listener that is called as soon as the FormData has been initialized with the request parameters but before any of the init, validation, or process listeners are run. The listener's submitted method may throw a FormProcessException to signal that any further processing of the form should be aborted.

Parameters:
listener - a submission listener to run every time the form is submitted
See Also:
FormModel.addSubmissionListener(com.arsdigita.bebop.event.FormSubmissionListener)

removeSubmissionListener

public void removeSubmissionListener(FormSubmissionListener listener)
Removes the specified submission listener from the list of submission listeners (if it had previously been added).

Parameters:
listener - the submission listener to remove

fireSubmitted

protected void fireSubmitted(FormSectionEvent e)
                      throws FormProcessException
Calls the submitted method on all registered submission listeners.

Parameters:
e - the event to pass to the listeners
Throws:
FormProcessException - if one of the listeners throws such an exception.

forwardSubmission

protected void forwardSubmission()

createSubmissionListener

protected FormSubmissionListener createSubmissionListener()
Creates the submission listener that forwards submission events to this form section.

Returns:
a submission listener that forwards submission events to this form section.

addInitListener

public void addInitListener(FormInitListener listener)
Adds a listener for form initialization events. Initialization events occur when a form is initially requested by the user, but not when the form is subsequently submitted. They typically perform actions such as querying the database for existing values to set up an edit form, or obtaining a sequence value to set up a create form.

Parameters:
listener - an instance of a class that implements the FormInitListener interface

removeInitListener

public void removeInitListener(FormInitListener listener)
Removes the specified init listener from the list of init listeners (if it had previously been added).

Parameters:
listener - the init listener to remove

fireInit

protected void fireInit(FormSectionEvent e)
                 throws FormProcessException
Calls the init method on all registered init listeners.

Parameters:
e - the event to pass to the listeners
Throws:
FormProcessException - if one of the listeners throws such an exception.

forwardInit

protected void forwardInit()

createInitListener

protected FormInitListener createInitListener()
Creates the init listener that forwards init events to this form section.

Returns:
an init listener that forwards init events to this form section.

addValidationListener

public void addValidationListener(FormValidationListener listener)
Adds a validation listener, implementing a custom validation check that applies to the form as a whole. Useful for checks that require examination of the values of more than one parameter.

Parameters:
listener - an instance of a class that implements the FormValidationListener interface

removeValidationListener

public void removeValidationListener(FormValidationListener listener)
Removes the specified validation listener from the list of validation listeners (if it had previously been added).

Parameters:
listener - a validation listener

fireValidate

protected void fireValidate(FormSectionEvent e)
Calls the validate method on all registered validation listeners.

Parameters:
e - the event to pass to the listeners

forwardValidation

protected void forwardValidation()

createValidationListener

protected FormValidationListener createValidationListener()
Create the validation listener that forwards validation events to this form section.

Returns:
a validation listener that forwards validation events to this form section.

addProcessListener

public void addProcessListener(FormProcessListener listener)
Adds a listener for form processing events.

Process events only occur after a form submission has been successfully validated. They are typically used to perform a database transaction or other operation based on the submitted data.

Process listeners are executed in the order in which they are added.

Parameters:
listener - an instance of a class that implements the FormProcessListener interface

removeProcessListener

public void removeProcessListener(FormProcessListener listener)
Removes the specified process listener from the list of process listeners (if it had previously been added).

Parameters:
listener - the process listener to remove

forwardProcess

protected void forwardProcess()

createProcessListener

protected FormProcessListener createProcessListener()

fireProcess

protected void fireProcess(FormSectionEvent e)
                    throws FormProcessException
Calls the process method on all registered process listeners.

Parameters:
e - the event to pass to the listeners
Throws:
FormProcessException - if one of the listeners throws such an exception.

process

public FormData process(PageState data)
                 throws javax.servlet.ServletException
Since a form section cannot be processed, always throws an error. (Processing of form sections is done by the form in which the section is contained.)

Throws:
javax.servlet.ServletException - because processing a form section is not meaningful.

addCancelListener

public void addCancelListener(FormCancelListener listener)
Adds a listener for form cancellation events. Cancellation listeners are typically used to clean-up page state and potentially intermediate changes to the database.

Parameters:
listener - an instance of a class that implements the FormCancelListener interface

removeCancelListener

public void removeCancelListener(FormCancelListener listener)
Removes the specified cancellation listener from the list of cancellation listeners (if it had previously been added).

Parameters:
listener - the cancellation listener to remove

fireCancel

protected void fireCancel(FormSectionEvent e)
                   throws FormProcessException
Calls the cancel method on all registered cancellation listeners.

Parameters:
e - the event to pass to the listeners
Throws:
FormProcessException - if one of the listeners throws such an exception.

register

public void register(Form f,
                     FormModel m)
Traverses the children this FormSection, collecting parameter models and listeners into the supplied FormModel. Sets implicit pointers of widgets in this FormSection to the supplied Form.

Specified by:
register in interface Component
Overrides:
register in class SimpleComponent
Parameters:
f - pointer to the form that is set inside Widgets within this FormSection
m - the FormModel in which to merge ParameterModels and Listeners

getModel

protected final FormModel getModel()
Accessor method for this form's FormModel.

Returns:
FormModel The model of this form.

lock

public void lock()
Locks this FormSection, its FormModel, and the implicit Container.

Specified by:
lock in interface Lockable
Overrides:
lock in class SimpleComponent

respond

public void respond(PageState state)
             throws javax.servlet.ServletException
Description copied from interface: Component

Responds to the request. This method is only called if the request was made from a link or form that the component put on the page in the PageState.stateAsURL() previous request.

No output should be generated on the HTTP response. The component can store intermediate results in the state by calling setAttribute.

This method is called before any output is printed to the HTTP response so that the component can forward to a different page and thereby commit the response.

Specified by:
respond in interface Component
Overrides:
respond in class SimpleComponent
Parameters:
state - the current page state
Throws:
javax.servlet.ServletException

getPanel

public Container getPanel()
Returns the implicit Container of this FormSection. This must not be final, because MetaFrom needs to override it.


children

public Iterator children()
Returns an iterator over the children of this component. If the component has no children, returns an empty iterator (not null !).

Specified by:
children in interface Component
Overrides:
children in class SimpleComponent

generateXML

public void generateXML(PageState pageState,
                        Element parent)
Builds an XML subtree for this component under the specified parent. Uses the request values stored in state.

This method generates DOM to be used with the XSLT template to produce the appropriate output.

Specified by:
generateXML in interface Component
Overrides:
generateXML in class SimpleComponent
Parameters:
pageState - the state of the current page
parent - the node that will be used to write to

add

public void add(Component pc)
Adds a component to this container.

Specified by:
add in interface Container
Parameters:
pc - the component to add to this container

add

public void add(Component pc,
                int constraints)
Adds a component with the specified layout constraints to this container. Layout constraints are defined in each layout container as static ints. Use a bitwise OR to specify multiple constraints.

Specified by:
add in interface Container
Parameters:
pc - the component to add to this container
constraints - layout constraints (a bitwise OR of static ints in the particular layout)

contains

public boolean contains(Object o)
Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that (o==null ? e==null : o.equals(e)). This method returns true only if the component has been directly added to this container. If this container contains another container that contains this component, this method returns false.

Specified by:
contains in interface Container
Parameters:
o - element whose presence in this container is to be tested
Returns:
true if this Container contains the specified component directly; false otherwise.

get

public Component get(int index)
Returns the Component at the specified position. Each call to add() increments the index. This method should be used in conjunction with indexOf

Specified by:
get in interface Container
Parameters:
index - The index of the item to be retrieved from this Container. Since the user has no control over the index of added components (other than counting each call to add), this method should be used in conjunction with indexOf.
Returns:
the component at the specified position in this container

indexOf

public int indexOf(Component pc)
Specified by:
indexOf in interface Container
Parameters:
pc - component to search for
Returns:
the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element.

isEmpty

public boolean isEmpty()
Determines whether the container contains any components.

Specified by:
isEmpty in interface Container
Returns:
true if this container contains no components false otherwise.

size

public int size()
Returns the number of elements in this container. This does not recursively count the components indirectly contained in this container.

Specified by:
size in interface Container
Returns:
the number of components directly in this container.


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 21 2004:2337 UTC