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 Field

    java.lang.Object
      org.apache.cocoon.forms.formmodel.AbstractWidget
          org.apache.cocoon.forms.formmodel.Field

All Implemented Interfaces:
  DataWidget, org.apache.cocoon.util.location.Locatable, SelectableWidget, ValidationErrorAware, ValueChangedListenerEnabled, Widget

Direct Known Subclasses:
  AggregateField, CalculatedField, CaptchaField, RepeaterFilterField

public class Field
extends AbstractWidget
implements ValidationErrorAware, DataWidget, SelectableWidget, ValueChangedListenerEnabled

A general-purpose Widget that can hold one value. A Field widget can be associated with a `Datatype`, and thus a Field widget can be used to edit different kinds of data, such as strings, numbers and dates. A Datatype can also have an associated SelectionList, so that the value for the Field can be selected from a list, rather than being entered in a textbox. The validation of the field is delegated to its associated Datatype.

Version:
  $Id: Field.java 587759 2007-10-24 03:00:37Z vgritsenko $

Field Summary
`protected String` | `enteredValue`
`protected boolean` | `required`
`protected SelectionList` | `selectionList` Overrides selection list defined in FieldDefinition, if any.
`static String` | `SUGGESTED_LABEL_ATTR` If the field was rendered as a suggestion-list and the user chose one of the suggestions, the field's value is the chosen item's value and the `SUGGESTED_LABEL_ATTR` field attribute contains the chosen item's label.
`protected ValidationError` | `validationError`
`protected Object` | `value`
`protected static int` | `VALUE_DISPLAY_PARSE_ERROR` Value state indicating that validate() has been called when state was VALUE_PARSE_ERROR.
`protected static int` | `VALUE_DISPLAY_VALIDATION` Value state indicating that value validation has occured, and the validation error, if any, should be displayed.
`protected static int` | `VALUE_PARSE_ERROR` Value state indicating that a parse error was encountered but should not yet be displayed.
`protected static int` | `VALUE_PARSED` Value state indicating that a value has been parsed, but needs to be validated (that must occur before the value is given to the application)
`protected static int` | `VALUE_UNPARSED` Value state indicating that a new value has been read from the request, but has not yet been parsed.
`protected static int` | `VALUE_VALIDATED` Value state indicating that validation has occured, but that any error should not yet be displayed.
`protected static int` | `VALUE_VALIDATING` Transient value state indicating that validation is going on.
`protected int` | `valueState` Transient widget processing state indicating that the widget is currently validating (used to avoid endless loops when a validator calls getValue).

Fields inherited from class org.apache.cocoon.forms.formmodel.AbstractWidget
`wasValid`

Fields inherited from interface org.apache.cocoon.forms.formmodel.Widget
`PATH_SEPARATOR`

Constructor Summary
`Field(FieldDefinition fieldDefinition)`

Method Summary
`void` | `addValueChangedListener(ValueChangedListener listener)` Adds a ValueChangedListener to this widget instance.
`protected String` | `applyWhitespaceTrim(String value)`
`void` | `broadcastEvent(WidgetEvent event)` Broadcast an event previously queued by this widget to its event listeners.
`void` | `generateItemSaxFragment(ContentHandler contentHandler, Locale locale)` Generates nested additional content nested inside the main element for this widget which is generated by `AbstractWidget.generateSaxFragment(ContentHandler, Locale)` The implementation on the AbstractWidget level inserts no additional XML.
`Datatype` | `getDatatype()`
`WidgetDefinition` | `getDefinition()` Get this widget's definition.
`FieldDefinition` | `getFieldDefinition()`
`String` | `getSuggestionLabel()` If the user has chosen an item in a suggestion list, returns that item's label.
`SelectionList` | `getSuggestionList()`
`ValidationError` | `getValidationError()` Returns the validation error, if any.
`Object` | `getValue()` Get the value of a widget.
`org.apache.cocoon.xml.AttributesImpl` | `getXMLElementAttributes()` Adds the @required attribute
`String` | `getXMLElementName()` The XML element name used in `AbstractWidget.generateSaxFragment(ContentHandler, Locale)` to produce the wrapping element for all the XML-instance-content of this Widget.
`boolean` | `hasValueChangedListeners()`
`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` | `isSuggested()` If this field has a selection-list, indicates if the value comes from that list or if a new value was input by the user.
`void` | `readFromRequest(FormContext formContext)` Lets this widget read its data from a request.
`protected void` | `readFromRequest(String newEnteredValue)`
`void` | `removeValueChangedListener(ValueChangedListener listener)`
`void` | `setRequired(boolean required)`
`void` | `setSelectionList(Object model, String valuePath, String labelPath)` Set this field's selection list using values from an in-memory object.
`void` | `setSelectionList(SelectionList selectionList)` Set this field's selection list.
`void` | `setSelectionList(String uri)` Read this field's selection list from an external source.
`void` | `setSuggestionLabel(String label)` Set the suggestion label associated to the widget's current value.
`void` | `setValidationError(ValidationError error)` Set a validation error on this field.
`void` | `setValue(Object newValue)` Sets the value of this widget.
`boolean` | `validate()` Validates this widget and returns the outcome.

Methods inherited from class org.apache.cocoon.forms.formmodel.AbstractWidget
`addValidator, generateDisplayData, generateLabel, generateSaxFragment, getAttribute, getChild, getCombinedState, getForm, getFullName, getId, getLocation, getName, getParent, getRequestParameterName, getState, getWidget, isValid, lookupWidget, removeAttribute, removeValidator, setAttribute, setParent, setState, toString, widgetNameChanged`

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
`addValidator, generateLabel, generateSaxFragment, getAttribute, getCombinedState, getForm, getFullName, getId, getLocation, getName, getParent, getRequestParameterName, getState, getWidget, isValid, lookupWidget, removeAttribute, removeValidator, setAttribute, setParent, setState`

Field Detail

### SUGGESTED_LABEL_ATTR

    public static final String SUGGESTED_LABEL_ATTR

  If the field was rendered as a suggestion-list and the user chose one of the suggestions, the field's value is the chosen item's value and the `SUGGESTED_LABEL_ATTR` field attribute contains the chosen item's label.

  Since:
    2.1.9
  See Also:
    `isSuggested()`, Constant Field Values

### VALUE_UNPARSED

    protected static final int VALUE_UNPARSED

  Value state indicating that a new value has been read from the request, but has not yet been parsed.

  See Also:
    Constant Field Values

### VALUE_PARSED

    protected static final int VALUE_PARSED

  Value state indicating that a value has been parsed, but needs to be validated (that must occur before the value is given to the application)

  See Also:
    Constant Field Values

### VALUE_PARSE_ERROR

    protected static final int VALUE_PARSE_ERROR

  Value state indicating that a parse error was encountered but should not yet be displayed.

  See Also:
    Constant Field Values

### VALUE_DISPLAY_PARSE_ERROR

    protected static final int VALUE_DISPLAY_PARSE_ERROR

  Value state indicating that validate() has been called when state was VALUE_PARSE_ERROR. This makes the error visible on output.

  See Also:
    Constant Field Values

### VALUE_VALIDATING

    protected static final int VALUE_VALIDATING

  Transient value state indicating that validation is going on.

  See Also:
    `validate()`, Constant Field Values

### VALUE_VALIDATED

    protected static final int VALUE_VALIDATED

  Value state indicating that validation has occured, but that any error should not yet be displayed.

  See Also:
    Constant Field Values

### VALUE_DISPLAY_VALIDATION

    protected static final int VALUE_DISPLAY_VALIDATION

  Value state indicating that value validation has occured, and the validation error, if any, should be displayed.

  See Also:
    Constant Field Values

### selectionList

    protected SelectionList selectionList

  Overrides selection list defined in FieldDefinition, if any.

### enteredValue

    protected String enteredValue

### value

    protected Object value

### required

    protected boolean required

### valueState

    protected int valueState

  Transient widget processing state indicating that the widget is currently validating (used to avoid endless loops when a validator calls getValue).

### validationError

    protected ValidationError validationError

Constructor Detail

### Field

    public Field(FieldDefinition fieldDefinition)

Method Detail

### getDefinition

    public WidgetDefinition getDefinition()

  Description copied from interface: `Widget`
  Get this widget's definition.

  Specified by:
    `getDefinition` in interface `Widget`
  Specified by:
    `getDefinition` in class `AbstractWidget`
  Returns:
    the widgetDefinition from which this widget was instantiated. (See `WidgetDefinition.createInstance()`)

### getFieldDefinition

    public final FieldDefinition getFieldDefinition()

### initialize

    public void initialize()

  Description copied from interface: `Widget`
  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`
  Overrides:
    `initialize` in class `AbstractWidget`

### isSuggested

    public boolean isSuggested()

  If this field has a selection-list, indicates if the value comes from that list or if a new value was input by the user.

  Returns:
    true if the user has chosen a suggested value
  Since:
    2.1.9

### setSuggestionLabel

    public void setSuggestionLabel(String label)

  Set the suggestion label associated to the widget's current value. This is used to initialize a combobox's rendering. If not such label exists, the widget's value is used.

  Since:
    2.1.9

### getSuggestionLabel

    public String getSuggestionLabel()

  If the user has chosen an item in a suggestion list, returns that item's label.

  Returns:
    the item's label, or `null` if the user entered a new value or if there's not suggestion list.
  Since:
    2.1.9

### 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`
  Overrides:
    `getValue` in class `AbstractWidget`

### setValue

    public void setValue(Object newValue)

  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`
  Overrides:
    `setValue` in class `AbstractWidget`

### readFromRequest

    public void readFromRequest(FormContext formContext)

  Description copied from interface: `Widget`
  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.

  Specified by:
    `readFromRequest` in interface `Widget`

### readFromRequest

    protected void readFromRequest(String newEnteredValue)

### applyWhitespaceTrim

    protected String applyWhitespaceTrim(String value)

### 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`
  Overrides:
    `validate` in class `AbstractWidget`
  See Also:
    `Widget.validate()`

### getValidationError

    public ValidationError getValidationError()

  Returns the validation error, if any. There will always be a validation error in case the `validate()` method returned false.
  This method does not cause parsing to take effect, use `getValue()` if value is not parsed yet.

  Specified by:
    `getValidationError` in interface `ValidationErrorAware`

### setValidationError

    public void setValidationError(ValidationError error)

  Set a validation error on this field. This allows fields to be externally marked as invalid by application logic.

  Specified by:
    `setValidationError` in interface `ValidationErrorAware`
  Parameters:
    `error` - the validation error

### isRequired

    public boolean isRequired()

  Specified by:
    `isRequired` in interface `Widget`
  Overrides:
    `isRequired` in class `AbstractWidget`

### setRequired

    public void setRequired(boolean required)

### getXMLElementName

    public String getXMLElementName()

  Description copied from class: `AbstractWidget`
  The XML element name used in `AbstractWidget.generateSaxFragment(ContentHandler, Locale)` to produce the wrapping element for all the XML-instance-content of this Widget.

  Specified by:
    `getXMLElementName` in class `AbstractWidget`
  Returns:
    "field"

### getXMLElementAttributes

    public org.apache.cocoon.xml.AttributesImpl getXMLElementAttributes()

  Adds the @required attribute

  Overrides:
    `getXMLElementAttributes` in class `AbstractWidget`
  Returns:
    the attributes for the main element for this widget's sax-fragment.

### generateItemSaxFragment

    public void generateItemSaxFragment(ContentHandler contentHandler,
                                        Locale locale)
                                 throws SAXException

  Description copied from class: `AbstractWidget`
  Generates nested additional content nested inside the main element for this widget which is generated by `AbstractWidget.generateSaxFragment(ContentHandler, Locale)` The implementation on the AbstractWidget level inserts no additional XML. Subclasses need to override to insert widget specific content.

  Overrides:
    `generateItemSaxFragment` in class `AbstractWidget`
  Parameters:
    `contentHandler` - to send the SAX events to
    `locale` - in which context potential content needs to be put.
  Throws:
    `SAXException`

### setSelectionList

    public void setSelectionList(SelectionList selectionList)

  Set this field's selection list.

  Specified by:
    `setSelectionList` in interface `SelectableWidget`
  Parameters:
    `selectionList` - The new selection list.

### setSelectionList

    public void setSelectionList(String uri)

  Read this field's selection list from an external source. All Cocoon-supported protocols can be used. The format of the XML produced by the source should be the same as in case of inline specification of the selection list, thus the root element should be a `fd:selection-list` element.

  Specified by:
    `setSelectionList` in interface `SelectableWidget`
  Parameters:
    `uri` - The URI of the source.

### setSelectionList

    public void setSelectionList(Object model,
                                 String valuePath,
                                 String labelPath)

  Set this field's selection list using values from an in-memory object. The `object` parameter should point to a collection (Java collection or array, or Javascript array) of objects. Each object belonging to the collection should have a value property and a label property, whose values are used to specify the `value` attribute and the contents of the `fd:label` child element of every `fd:item` in the list.

  Access to the values of the above mentioned properties is done via XPath expressions.

  Specified by:
    `setSelectionList` in interface `SelectableWidget`
  Parameters:
    `model` - The collection used as a model for the selection list.
    `valuePath` - An XPath expression referring to the attribute used to populate the values of the list's items.
    `labelPath` - An XPath expression referring to the attribute used to populate the labels of the list's items.

### getSuggestionList

    public SelectionList getSuggestionList()

### getDatatype

    public Datatype getDatatype()

  Specified by:
    `getDatatype` in interface `DataWidget`

### addValueChangedListener

    public void addValueChangedListener(ValueChangedListener listener)

  Adds a ValueChangedListener to this widget instance. Listeners defined on the widget instance will be executed in addtion to any listeners that might have been defined in the widget definition.

  Specified by:
    `addValueChangedListener` in interface `ValueChangedListenerEnabled`

### removeValueChangedListener

    public void removeValueChangedListener(ValueChangedListener listener)

  Specified by:
    `removeValueChangedListener` in interface `ValueChangedListenerEnabled`

### hasValueChangedListeners

    public boolean hasValueChangedListeners()

  Specified by:
    `hasValueChangedListeners` in interface `ValueChangedListenerEnabled`

### broadcastEvent

    public void broadcastEvent(WidgetEvent event)

  Description copied from interface: `Widget`
  Broadcast an event previously queued by this widget to its event listeners.

  Specified by:
    `broadcastEvent` in interface `Widget`
  Overrides:
    `broadcastEvent` in class `AbstractWidget`

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.