org.apache.cocoon.forms.formmodel
Class AbstractWidget

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

All Implemented Interfaces:

org.apache.cocoon.util.location.Locatable, Widget

Direct Known Subclasses:

AbstractContainerWidget, Action, BooleanField, Field, GoogleMap, ImageMap, Messages, MultiValueField, Output, Repeater, Tree, Upload

public abstract class AbstractWidget

extends Object

implements Widget

Abstract base class for Widget implementations. Provides functionality common to many widgets.

Version:

$Id: AbstractWidget.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Field Summary

protected boolean

wasValid The result of the last call to validate().

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

PATH_SEPARATOR

Constructor Summary

protected

AbstractWidget(AbstractWidgetDefinition definition)

Method Summary

void	addValidator(WidgetValidator validator) Add a validator to this widget instance.
void	broadcastEvent(WidgetEvent event) Broadcast an event previously queued by this widget to its event listeners. Abstract implementation throws a UnsupportedOperationException.
protected void	generateDisplayData(ContentHandler contentHandler) Delegates to the getDefinition() of this widget to generate a common set of 'display' data.
protected void	generateItemSaxFragment(ContentHandler contentHandler, Locale locale) Generates nested additional content nested inside the main element for this widget which is generated by generateSaxFragment(ContentHandler, Locale) The implementation on the AbstractWidget level inserts no additional XML.
void	generateLabel(ContentHandler contentHandler) Generates SAX events for the label of this widget. The label will not be wrapped inside another element. Delegates to the getDefinition() to generate the 'label' part of the display-data of this widget.
void	generateSaxFragment(ContentHandler contentHandler, Locale locale) Generates an XML representation of this widget. The startDocument and endDocument SAX events will not be called. It is assumed that the prefix for the CForms namespace mentioned in Constants.FI_PREFIX is already declared (by the caller or otherwise). This will generate some standard XML consisting of a simple wrapper element (name provided by getXMLElementName()) with attributes (provided by getXMLElementAttributes() around anything injected in by both generateDisplayData(ContentHandler) and generateItemSaxFragment(ContentHandler, Locale).
Object	getAttribute(String name) Retrieves an attribute on this widget.
protected Widget	getChild(String id) Concrete widgets that contain actual child widgets should override to return the actual child-widget.
WidgetState	getCombinedState() Get the widget's combined state, which is the strictest of its own state and parent state.
abstract WidgetDefinition	getDefinition() Concrete subclasses should allow access to their underlaying Definition through this method.
Form	getForm()
String	getFullName()
String	getId() Gets the id of this widget.
org.apache.cocoon.util.location.Location	getLocation()
String	getName()
Widget	getParent()
String	getRequestParameterName()
WidgetState	getState() Get the widget's own state.
Object	getValue() Get the value of a widget.
Widget	getWidget(String id)
protected org.apache.cocoon.xml.AttributesImpl	getXMLElementAttributes() The XML attributes used in generateSaxFragment(ContentHandler, Locale) to be placed on the wrapping element for all the XML-instance-content of this Widget.
protected abstract String	getXMLElementName() The XML element name used in generateSaxFragment(ContentHandler, Locale) to produce the wrapping element for all the XML-instance-content of this Widget.
void	initialize() Called after widget's environment has been setup, to allow for any contextual initalization, such as looking up case widgets for union widgets.
boolean	isRequired()
boolean	isValid() Return the current validation state.
Widget	lookupWidget(String path) Finds a widget relative to this one based on a path-like string (/-delimted) into the widget-tree structure.
void	removeAttribute(String name) Removes the named attribute from this widget.
boolean	removeValidator(WidgetValidator validator) Remove a validator from this widget instance
void	setAttribute(String name, Object value) Sets an attribute on this widget.
void	setParent(Widget widget) Sets the parent-widget of this widget.
void	setState(WidgetState state) Set the widget's own state.
void	setValue(Object object) Sets the value of this widget.
String	toString()
boolean	validate() Validates this widget and returns the outcome.
protected void	widgetNameChanged() Should be called when a widget's own name has changed, in order to clear internal caches used to compute request parameters.

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

readFromRequest

Field Detail

wasValid

protected boolean wasValid

The result of the last call to validate().

Constructor Detail

AbstractWidget

protected AbstractWidget(AbstractWidgetDefinition definition)

Method Detail

initialize

public void initialize()

Called after widget's environment has been setup, to allow for any contextual initalization, such as looking up case widgets for union widgets.

Specified by:

initialize in interface Widget

getId

public String getId()

Gets the id of this widget.

Specified by:

getId in interface Widget

Returns:

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

getName

public String getName()

Specified by:

getName in interface Widget

Returns:

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

getDefinition

public abstract WidgetDefinition getDefinition()

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 getId(), getLocation(), validate(), generateLabel(ContentHandler) and generateDisplayData(ContentHandler) to avoid NPE's.

Specified by:

getDefinition in interface Widget

Returns:

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

getLocation

public org.apache.cocoon.util.location.Location getLocation()

Specified by:

getLocation in interface Widget

Returns:

the location-information (file, line and column) where this widget was configured.

getParent

public final Widget getParent()

Specified by:

getParent in interface Widget

Returns:

The parent-widget of this widget.

setParent

public void setParent(Widget widget)

Sets the parent-widget of this widget. This is a write-once property.

Specified by:

setParent in interface Widget

Parameters:

widget - the parent-widget of this one.

Throws:

IllegalStateException - when the parent had already been set.

getForm

public Form getForm()

Specified by:

getForm in interface Widget

Returns:

the form where this widget belongs to.

getState

public WidgetState getState()

Description copied from interface: Widget

Get the widget's own state. Note that this state is not the one actually considered for handling requests and producing output. For these matters, the combined state is used.

Specified by:

getState in interface Widget

Returns:

the widget's own state

See Also:

Widget.getCombinedState()

setState

public void setState(WidgetState state)

Description copied from interface: Widget

Set the widget's own state. This may change its combined state, and those of its children, if any.

Specified by:

setState in interface Widget

Parameters:

state - the new wiget state

getCombinedState

public WidgetState getCombinedState()

Description copied from interface: Widget

Get the widget's combined state, which is the strictest of its own state and parent state. This combined state is the one that will be used by the widget to know if request parameters should be considered and if some output must be produced.

Specified by:

getCombinedState in interface Widget

Returns:

the combined state

See Also:

WidgetState.strictest(WidgetState, WidgetState)

widgetNameChanged

protected void widgetNameChanged()

Should be called when a widget's own name has changed, in order to clear internal caches used to compute request parameters.

getFullName

public String getFullName()

Specified by:

getFullName in interface Widget

Returns:

the name prefixed with the namespace, this name should be unique accross all widgets on the form.

getRequestParameterName

public String getRequestParameterName()

Specified by:

getRequestParameterName in interface Widget

Returns:

the id prefixed with the namespace, this name should be unique accross all widgets on the form.

lookupWidget

public Widget lookupWidget(String path)

Description copied from interface: Widget

Finds a widget relative to this one based on a path-like string (/-delimted) into the widget-tree structure. This supports '../' and '/' to point to

Specified by:

lookupWidget in interface Widget

Returns:

the found widget or null if allong the traversal of the path an invalid section was encountered.

getChild

protected Widget getChild(String id)

Concrete widgets that contain actual child widgets should override to return the actual child-widget.

Parameters:

id - of the child-widget

Returns:

null if not overriden.

getWidget

public Widget getWidget(String id)

Specified by:

getWidget in interface Widget

getValue

public Object getValue()

Description copied from interface: Widget

Get the value of a widget.

Not all widgets do have a value (notably ContainerWidgets, but this method is provided here as a convenience to ease writing and avoiding casts.

Specified by:

getValue in interface Widget

Returns:

the value of the widget.

setValue

public void setValue(Object object)

Description copied from interface: Widget

Sets the value of this widget.

Not all widgets do have a value (notably ContainerWidgets, but this method is provided here as a convenience to ease writing and avoiding casts.

Specified by:

setValue in interface Widget

Parameters:

object - the new widget's value.

isRequired

public boolean isRequired()

Specified by:

isRequired in interface Widget

Returns:

whether this widget is required to be filled in. As with Widget.getValue(), for some widgets this may not make sense, those should return false here.

broadcastEvent

public void broadcastEvent(WidgetEvent event)

Broadcast an event previously queued by this widget to its event listeners. Abstract implementation throws a UnsupportedOperationException. Concrete subclass widgets need to override when supporting event broadcasting.

Specified by:

broadcastEvent in interface Widget

addValidator

public void addValidator(WidgetValidator validator)

Add a validator to this widget instance.

Specified by:

addValidator in interface Widget

Parameters:

validator -

removeValidator

public boolean removeValidator(WidgetValidator validator)

Remove a validator from this widget instance

Specified by:

removeValidator in interface Widget

Parameters:

validator -

Returns:

true if the validator was found.

validate

public boolean validate()

Description copied from interface: Widget

Validates this widget and returns the outcome. Possible error messages are remembered by the widget itself and will be part of the XML produced by this widget in its Widget.generateSaxFragment(ContentHandler, Locale) method.

Specified by:

validate in interface Widget

Returns:

true to indicate all validations were ok, false otherwise

See Also:

Widget.validate()

isValid

public boolean isValid()

Description copied from interface: Widget

Return the current validation state. This method delivers the same result as the last call to Widget.validate(). The validation process is not started again. If the value of this widget has changed since the latest call to Widget.validate(), the result of this method is out of date.

Specified by:

isValid in interface Widget

Returns:

The result of the last call to Widget.validate().

See Also:

Widget.isValid()

generateLabel

public void generateLabel(ContentHandler contentHandler)
                   throws SAXException

Generates SAX events for the label of this widget. The label will not be wrapped inside another element. Delegates to the getDefinition() to generate the 'label' part of the display-data of this widget. Subclasses should override if the getDefinition can return null to avoid NPE's

Specified by:

generateLabel in interface Widget

Parameters:

contentHandler -

Throws:

SAXException

generateItemSaxFragment

protected void generateItemSaxFragment(ContentHandler contentHandler,
                                       Locale locale)
                                throws SAXException

Generates nested additional content nested inside the main element for this widget which is generated by generateSaxFragment(ContentHandler, Locale) The implementation on the AbstractWidget level inserts no additional XML. Subclasses need to override to insert widget specific content.

Parameters:

contentHandler - to send the SAX events to

locale - in which context potential content needs to be put.

Throws:

SAXException

getXMLElementName

protected abstract String getXMLElementName()

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

Returns:

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

getXMLElementAttributes

protected org.apache.cocoon.xml.AttributesImpl getXMLElementAttributes()

The XML attributes used in generateSaxFragment(ContentHandler, Locale) to be placed on the wrapping element for all the XML-instance-content of this Widget. This automatically adds @id=getRequestParameterName() to that element. Concrete subclasses should call super.getXMLElementAttributes and possibly add additional attributes. Note: the @id is not added for those widgets who's getId() returns null (e.g. top-level container widgets like 'form'). The contract of returning a non-null AttributesImpl is however maintained.

Returns:

the attributes for the main element for this widget's sax-fragment.

generateDisplayData

protected void generateDisplayData(ContentHandler contentHandler)
                            throws SAXException

Delegates to the getDefinition() of this widget to generate a common set of 'display' data. (i.e. help, label, hint,...) Subclasses should override if the getDefinition can return null to avoid NPE's.

Parameters:

contentHandler - where to send the SAX events to.

Throws:

SAXException

See Also:

WidgetDefinition.generateDisplayData(ContentHandler)

generateSaxFragment

public void generateSaxFragment(ContentHandler contentHandler,
                                Locale locale)
                         throws SAXException

Generates an XML representation of this widget. The startDocument and endDocument SAX events will not be called. It is assumed that the prefix for the CForms namespace mentioned in Constants.FI_PREFIX is already declared (by the caller or otherwise). This will generate some standard XML consisting of a simple wrapper element (name provided by getXMLElementName()) with attributes (provided by getXMLElementAttributes() around anything injected in by both generateDisplayData(ContentHandler) and generateItemSaxFragment(ContentHandler, Locale).

 <fi:getXMLElementName() getXMLElementAttributes() >
   generateDisplayData(ContentHandler) (i.e. help, label, ...)

   generateItemSaxFragment(ContentHandler, Locale)
 </fi:getXMLElementName() >
 

Specified by:

generateSaxFragment in interface Widget

Parameters:

contentHandler - to send the SAX events to

locale - in which context potential content needs to be put.

Throws:

SAXException

getAttribute

public Object getAttribute(String name)

Description copied from interface: Widget

Retrieves an attribute on this widget.

Specified by:

getAttribute in interface Widget

Parameters:

name - of the attribute to lookup

Returns:

the found attribute or null if none was found with that name.

setAttribute

public void setAttribute(String name,
                         Object value)

Description copied from interface: Widget

Sets an attribute on this widget. This can be used to store custom data with each widget.

Specified by:

setAttribute in interface Widget

removeAttribute

public void removeAttribute(String name)

Description copied from interface: Widget

Removes the named attribute from this widget.

Specified by:

removeAttribute in interface Widget

Parameters:

name - of the attribute

toString

public String toString()