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:

ValueChangedListenerEnabled, DataWidget, SelectableWidget, Widget, ValidationErrorAware, Locatable

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.html 1304258 2012-03-23 10:09:27Z ilgrosso $

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 SelectionList	suggestionList Overrides sugestion list defined in FieldDefinition, if any.
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() Concrete subclasses should allow access to their underlaying Definition through this method.
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.
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	setSuggestionList(SelectionList suggestionList) Set this field's suggestion list.
void	setSuggestionList(String uri) Read this field's selection list from an external source.
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.

suggestionList

protected SelectionList suggestionList

Overrides sugestion 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 class: AbstractWidget

Concrete subclasses should allow access to their underlaying Definition through this method. If subclasses decide to return null they should also organize own implementations of AbstractWidget.getId(), AbstractWidget.getLocation(), AbstractWidget.validate(), AbstractWidget.generateLabel(ContentHandler) and AbstractWidget.generateDisplayData(ContentHandler) to avoid NPE's.

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

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 ContainerWidgets, 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

Returns:

the value of the widget.

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 ContainerWidgets, 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

Parameters:

newValue - the new widget's value.

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

Returns:

true to indicate all validations were ok, false otherwise

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

Returns:

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

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

setSuggestionList

public void setSuggestionList(SelectionList suggestionList)

Set this field's suggestion list.

Parameters:

suggestionList - The new suggestion list.

Since:

2.1.12

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.

setSuggestionList

public void setSuggestionList(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.

Parameters:

uri - The URI of the source.

Since:

2.1.12

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

Broadcast an event previously queued by this widget to its event listeners. Abstract implementation throws a UnsupportedOperationException. Concrete subclass widgets need to override when supporting event broadcasting.

Specified by:

broadcastEvent in interface Widget

Overrides:

broadcastEvent in class AbstractWidget