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

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 `ContainerWidget`s, 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 `ContainerWidget`s, 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()

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.