org.apache.cocoon.forms.formmodel
Class MultiValueField

java.lang.Object
  extended byorg.apache.cocoon.forms.formmodel.AbstractWidget
      extended byorg.apache.cocoon.forms.formmodel.MultiValueField
All Implemented Interfaces:
DataWidget, org.apache.cocoon.util.location.Locatable, SelectableWidget, ValidationErrorAware, ValueChangedListenerEnabled, Widget

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

A MultiValueField is mostly the same as a normal Field, but can hold multiple values. A MultiValueField should have a Datatype which has a SelectionList, because the user will always select the values from a list. A MultiValueField has no concept of "required", you should instead use the ValueCountValidationRule to check how many items the user has selected.

A MultiValueField also has a Datatype associated with it. In case of MultiValueFields, this Datatype will always be an array type, thus Datatype.isArrayType() will always return true, and this in return has an influence on the kind of validation rules that can be used with the Datatype (see Datatype description for more information).

Version:
$Id: MultiValueField.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Field Summary
 
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
MultiValueField(MultiValueFieldDefinition definition)
           
 
Method Summary
 void addValueChangedListener(ValueChangedListener listener)
           
 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.
 ValidationError getValidationError()
           
 Object getValue()
          Get the value of a widget.
 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.
 void readFromRequest(FormContext formContext)
          Lets this widget read its data from a request.
 void removeValueChangedListener(ValueChangedListener listener)
           
 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 setValidationError(ValidationError error)
           
 void setValue(Object value)
          Sets the value of this widget.
 void setValues(Object[] values)
           
 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, getXMLElementAttributes, isRequired, 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, isRequired, isValid, lookupWidget, removeAttribute, removeValidator, setAttribute, setParent, setState
 

Constructor Detail

MultiValueField

public MultiValueField(MultiValueFieldDefinition definition)
Method Detail

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

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

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

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

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

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

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 value)
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

setValues

public void setValues(Object[] values)

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.

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

getValidationError

public ValidationError getValidationError()
Specified by:
getValidationError in interface ValidationErrorAware

setValidationError

public void setValidationError(ValidationError error)
Specified by:
setValidationError in interface ValidationErrorAware

getDatatype

public Datatype getDatatype()
Specified by:
getDatatype in interface DataWidget

addValueChangedListener

public void addValueChangedListener(ValueChangedListener listener)
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


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