org.apache.cocoon.forms.formmodel
Class Field

java.lang.Object
  extended byorg.apache.cocoon.forms.formmodel.AbstractWidget
      extended byorg.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.html 1304280 2012-03-23 11:18:01Z 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  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 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

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

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


Copyright 1999-2008 The Apache Software Foundation. All Rights Reserved.