org.apache.cocoon.woody.formmodel
Interface Widget

All Known Subinterfaces:

ContainerWidget, DataWidget, SelectableWidget

All Known Implementing Classes:

AbstractContainerWidget, AbstractWidget, Action, AggregateField, BooleanField, Field, Form, Messages, MultiValueField, Output, Repeater, Repeater.RepeaterRow, RepeaterAction, RowAction, RowAction.MoveDownAction, RowAction.MoveUpAction, Struct, Submit, Union, Upload

public interface Widget

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

• has an id, unique within its parent context widget. See getId().
• can have children (see getWidget(String), and 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(FormContext).
• can generate an XML representation of itself.

Because widgets can have children, the widgets form a widget tree, with its root being the Form widget.

A widget can have only a value, or only child widgets, or can have both a value and child widgets, or can have neither. This all depends on the widget implementation.

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(FormContext) 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:

CVS $Id: Widget.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Method Summary

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.
Form	getForm() Get the Form to which this widget belongs.
String	getFullyQualifiedId() Returns the id prefixed with the namespace, this name should be unique accross all widgets on the form.
String	getId() Returns the id of this widget.
String	getLocation() Gets the source location of this widget.
String	getNamespace() Gets the namespace of this widget.
Widget	getParent() Gets the parent of this widget.
Object	getValue() Returns the value of the widget.
Widget	getWidget(String id) Gets the child widget of this widget with the given id, or null if there isn't such a child.
boolean	isRequired() Returns wether this widget is required to be filled in.
void	readFromRequest(FormContext formContext) Lets this widget read its data from a request.
void	setParent(Widget widget) This method is called on a widget when it is added to a container.
void	setValue(Object object) Sets the value of this widget to the given object.
boolean	validate(FormContext formContext) Validates this widget and returns the outcome.

Method Detail

getLocation

String getLocation()

Gets the source location of this widget.

getId

String getId()

Returns the id of this widget.

getParent

Widget getParent()

Gets 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()

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

getNamespace

String getNamespace()

Gets the namespace of this widget. The combination of a widget's namespace with its id (see getId() gives the widget a form-wide unique name. In practice, the namespace consists of the id's of the widget's parent widgets, separated by dots.

getFullyQualifiedId

String getFullyQualifiedId()

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

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(FormContext formContext)

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.

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 Woody namespace mentioned in Constants.WI_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()

Returns the value of the widget. For some widgets (notably ContainerWidgets) this may not make sense, those should then simply return null here.

setValue

void setValue(Object object)

Sets the value of this widget to the given object. Some widgets may not support this method, those should throw an runtime exception if you try to set their value anyway.

isRequired

boolean isRequired()

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

getWidget

Widget getWidget(String id)

Gets the child widget of this widget with the given id, or null if there isn't such a child.

broadcastEvent

void broadcastEvent(WidgetEvent event)

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