org.apache.cocoon.forms.formmodel
Interface Widget

All Superinterfaces:
org.apache.cocoon.util.location.Locatable
All Known Subinterfaces:
ContainerWidget, DataWidget, SelectableWidget
All Known Implementing Classes:
AbstractContainerWidget, AbstractWidget, AggregateField, Field, MultiValueField, Output

public interface Widget
extends org.apache.cocoon.util.location.Locatable

Interface to be implemented by Widgets. In CForms, a form consists of a number of widgets. Each widget:

When a request is submitted, first the readFromRequest(FormContext) method of all widgets will be called so that they can read their value(s). Next, the validate() method will be called. Doing this in two steps allows the validation to compare values between widgets. See also the method Form.process(FormContext).

A Widget is created by calling the createInstance method on the a WidgetDefinition. A Widget holds all the data that is specific for a certain use of the widget (its value, validationerrors, ...), while the WidgetDefinition holds the data that is static accross all widgets. This keeps the Widgets small and light to create. This mechanism is similar to classes and objects in Java.

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

Field Summary
static char PATH_SEPARATOR
          Widget-Separator used in path-like notations
 
Method Summary
 void addValidator(WidgetValidator validator)
           
 void broadcastEvent(WidgetEvent event)
          Broadcast an event previously queued by this widget to its event listeners.
 void generateLabel(ContentHandler contentHandler)
          Generates SAX events for the label of this widget.
 void generateSaxFragment(ContentHandler contentHandler, Locale locale)
          Generates an XML representation of this widget.
 Object getAttribute(String name)
          Retrieves an attribute on this widget.
 WidgetState getCombinedState()
          Get the widget's combined state, which is the strictest of its own state and parent state.
 WidgetDefinition getDefinition()
          Get this widget's definition.
 Form getForm()
           
 String getFullName()
           
 String getId()
           
 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)
          Deprecated. getWidget got removed, use lookupWidget or getChild instead.
 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 readFromRequest(FormContext formContext)
          Lets this widget read its data from a request.
 void removeAttribute(String name)
          Removes the named attribute from this widget.
 boolean removeValidator(WidgetValidator validator)
           
 void setAttribute(String name, Object value)
          Sets an attribute on this widget.
 void setParent(Widget widget)
          This method is called on a widget when it is added to a container.
 void setState(WidgetState state)
          Set the widget's own state.
 void setValue(Object value)
          Sets the value of this widget.
 boolean validate()
          Validates this widget and returns the outcome.
 

Field Detail

PATH_SEPARATOR

public static final char PATH_SEPARATOR
Widget-Separator used in path-like notations

See Also:
lookupWidget(String), Constant Field Values
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.


getLocation

public org.apache.cocoon.util.location.Location getLocation()
Specified by:
getLocation in interface org.apache.cocoon.util.location.Locatable
Returns:
the source location of this widget.

getName

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

getId

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

getParent

public Widget getParent()
Returns:
the parent of this widget. If this widget is the root widget, this method returns null.

setParent

public void setParent(Widget widget)
This method is called on a widget when it is added to a container. You shouldn't call this method unless youre implementing a widget yourself (in which case it should be called when a widget is added as child of your widget).


getForm

public Form getForm()
Returns:
the Form to which this widget belongs. The form is the top-most ancestor of the widget.

getDefinition

public WidgetDefinition getDefinition()
Get this widget's definition.

Returns:
the widget's definition

getState

public WidgetState getState()
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.

Returns:
the widget's own state
See Also:
getCombinedState()

setState

public void setState(WidgetState state)
Set the widget's own state. This may change its combined state, and those of its children, if any.

Parameters:
state - the new wiget state

getCombinedState

public WidgetState getCombinedState()
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.

Returns:
the combined state
See Also:
WidgetState.strictest(WidgetState, WidgetState)

getFullName

public String getFullName()
Returns:
the name prefixed with the namespace, this name should be unique accross all widgets on the form.

getRequestParameterName

public String getRequestParameterName()
Returns:
the id prefixed with the namespace, this name should be unique accross all widgets on the form.

getWidget

public Widget getWidget(String id)
Deprecated. getWidget got removed, use lookupWidget or getChild instead.

Throws:
UnsupportedOperationException - indicating this method has been deprecated from the API, and will be removed from future releases.

lookupWidget

public Widget lookupWidget(String path)
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

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

readFromRequest

public void readFromRequest(FormContext formContext)
Lets this widget read its data from a request. At this point the Widget may try to convert the request parameter to its native datatype (if it is not a string), but it should not yet generate any validation errors.


validate

public boolean validate()
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 generateSaxFragment(ContentHandler, Locale) method.

Returns:
true to indicate all validations were ok, false otherwise

addValidator

public void addValidator(WidgetValidator validator)

removeValidator

public boolean removeValidator(WidgetValidator validator)

isValid

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

Returns:
The result of the last call to validate().

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).

Throws:
SAXException

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.

Throws:
SAXException

getValue

public Object getValue()
                throws UnsupportedOperationException
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.

Returns:
the value of the widget.
Throws:
UnsupportedOperationException - if this widget doesn't have a value.

setValue

public void setValue(Object value)
              throws UnsupportedOperationException
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.

Parameters:
value - the new widget's value.
Throws:
UnsupportedOperationException - if this widget doesn't have a value.

isRequired

public boolean isRequired()
Returns:
whether this widget is required to be filled in. As with 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.


getAttribute

public Object getAttribute(String name)
Retrieves an attribute on this 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)
Sets an attribute on this widget. This can be used to store custom data with each widget.


removeAttribute

public void removeAttribute(String name)
Removes the named attribute from this widget.

Parameters:
name - of the attribute


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