com.arsdigita.bebop
Class FormSection

java.lang.Object
  com.arsdigita.bebop.Completable
      com.arsdigita.bebop.SimpleComponent
          com.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:

• Divides a form into visual sections
• Serves as a container for form fragments that can function by themselves and can be dropped into other forms

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.