This project has retired. For details please refer to its Attic page.

org.apache.cocoon.forms.formmodel
Interface Widget

All Superinterfaces:

Locatable

All Known Subinterfaces:

ContainerWidget, DataWidget, SelectableWidget

All Known Implementing Classes:

AbstractContainerWidget, AbstractWidget, Action, AggregateField, BooleanField, CalculatedField, CaptchaField, EnhancedRepeater, Field, Form, GoogleMap, Group, ImageMap, Messages, MultiValueField, Output, Repeater, Repeater.RepeaterRow, RepeaterAction, RepeaterFilterField, RowAction, RowAction.MoveDownAction, RowAction.MoveUpAction, Struct, Submit, Tree, Union, Upload

public interface Widget
extends Locatable

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

• has an unique id within its parent context widget. See getId().
• can have a parent (see getParent().
• can hold a value (which can be any kind of object). See getValue().
• can read its value from a request object (and convert it from a string to its native type). See readFromRequest(FormContext).
• can validate itself. See validate().
• can generate an XML representation of itself.

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 1304258 2012-03-23 10:09:27Z 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()
Location	getLocation() Get the location of this object
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

static final char PATH_SEPARATOR

Widget-Separator used in path-like notations

See Also:

lookupWidget(String), Constant Field Values

Method Detail

initialize

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

Location getLocation()

Description copied from interface: Locatable

Get the location of this object

Specified by:

getLocation in interface Locatable

Returns:

the source location of this widget.

getName

String getName()

Returns:

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

getId

String getId()

Returns:

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

getParent

Widget getParent()

Returns:

the parent of this widget. If this widget is the root widget, this method returns null.

setParent

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

Form getForm()

Returns:

the Form to which this widget belongs. The form is the top-most ancestor of the widget.

getDefinition

WidgetDefinition getDefinition()

Get this widget's definition.

Returns:

the widget's definition

getState

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

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

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

String getFullName()

Returns:

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

getRequestParameterName

String getRequestParameterName()

Returns:

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

getWidget

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

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

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

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

void addValidator(WidgetValidator validator)

removeValidator

boolean removeValidator(WidgetValidator validator)

isValid

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

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

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

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

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

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

void broadcastEvent(WidgetEvent event)

Broadcast an event previously queued by this widget to its event listeners.

getAttribute

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

void setAttribute(String name,
                  Object value)

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

removeAttribute

void removeAttribute(String name)

Removes the named attribute from this widget.

Parameters:

name - of the attribute