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
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:

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

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

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.