org.apache.cocoon.forms.formmodel
Class AbstractWidget

java.lang.Object
  extended byorg.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()


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