com.taursys.xml
Class SelectField

java.lang.Object
  com.taursys.xml.Component
      com.taursys.xml.Parameter
          com.taursys.xml.AbstractField
              com.taursys.xml.SelectField

All Implemented Interfaces:

DocumentComponent, Element, MapperComponent

Direct Known Subclasses:

HTMLSelect

public class SelectField

extends AbstractField

This component is used to display and change a selection. This component, (using a DefaultSelectModel), can display a selection from a list of objects. It can also change the selection from user input.

This component can be used for a variety of purposes. It can provide a way to display a "description" rather than a "code" for a coded value. It can also serve to scope user input to a subset of values.

The selection is made and displayed using the property indicated by the displayPropertyName. The displayPropertyName is effectively the "selection key". If the displayPropertyName is null or blank, then the toString method is used instead. For example, given a list of Address objects, and a displayPropertyName of "zipCode", the display value for "Juneau, AK 99801 USA" would be "99801". To change the selection, you would supply a different zipCode from the list.

This component can function in three different ways, depending on the properties you set:

• input only - set the parameter property.
• output only - set the id property.
• input and output - set both the parameter and id properties.

When used for output, the value is rendered in the XML document as a text node by default. If you want the value to be rendered to an attribute of the node instead, you must change the renderer to an AttributeTextFieldRenderer and the the attribute property to the name of the attribute. For rendering with an HTML SELECT/OPTION, use the HTMLSelect component.

When used for input, this component receives its value from the InputDispatcher AFTER the openForm method of the ServletForm by default. If you want this component to receive its input earlier (at the same time as Parameters), set the earlyInputNotify property to true.

By default, this component uses a DefaultSelectModel. You can change this by overriding the createDefaultModel method or explicitly setting the model property.

Setting the List

The list must be a type of CollectionValueHolder (example: VOCollectionValueHolder or VOListValueHolder). The holder can contain any type of object (but they must all be instances of the same class).

If the list is an ObjectArrayValueHolder, then the toString() method is used as the display value (regardless of the displayPropertyName). If used in the bound mode, the whole object itself is stored in the target ValueHolder's object (regardless of the property names listed in the setListPropertyNames method). It is important to make sure that the valueHolder property is the same type as the objects in the ObjectArrayValueHolder or a ModelException will occur.

You can also preset the list in the constructor by passing it an array of Objects to be used for the list. The resulting list will be an ObjectArrayValueHolder.

The following is an example of this usage:

   SelectField color = new SelectField(new String[] {
       "Red", "Orange", "Yellow", "Green", "Blue", "Indigo", "Violet",
       });
   ...
   private void jbInit() throws Exception {
     ...
     color.setParameter("color");
     color.setId("color");
     ...
     this.add(color);
   }
 

This component can be used in a variety of ways. It can be used in an un-bound mode, where the current selection is maintained internally. It can also be used in a bound mode where the current selection is propagated to a value holder. When used in the bound mode, either a single property, or multiple properties can be set in the value holder. The following sections describe the required settings to make for each of the modes.

Un-bound Mode (uses internal VariantValueHolder)

When used in this mode this component uses an internal VariantValueHolder to hold the current selection. By default a VariantValueHolder is created with a data type of String. To set a different data type use the constructor which takes a data type as a parameter. (example new SelectField(DataTypes.TYPE_INT)).

To use this component in the un-bound mode, you must set the following properties:

• list - should be set to a type of CollectionHolder which holds the list of options (see "Setting the List").
• displayPropertyName - the name of the property to display (property of objects in list). Example: given a list of "Location" objects with a property called "locationName", use setDisplayPropertyName("locationName") to display the zipCode. IMPORTANT - The displayed property choosen must result in a unique list of values, otherwise the intended value may not be selected/displayed.
• listPropertyNames - set a single source property name in the list objects. Example: Given a list containing "Location" objects which has properties "zipCode", "cityName", "stateAbbr", and "country", to make the zipcode the internal value use setListPropertyNames(new String[] {"zipCode"}).

  If the list is an ObjectArrayValueHolder, then the property name should always be a single "value" (which is the default).

• propertyName - must be "value" (which is the default).
• nullDisplay - String to display in list for null selection. Example: "--- Nothing Selected ---"

Bound Mode

To use this component in the bound mode, use the same properties as described in the Un-bound Mode, plus the following additional properties:

• valueHolder - should be set to the target ValueHolder which contains the current selection and will be updated if the selection is changed.
• propertyName - set this to the first (or only) ValueHolder object property name which will be bound to the selection. Example: given a ValueHolder with an "Address" object which has a "zipCode" property, use setPropertyName("zipCode") to store the current selection in the "Address.zipCode" property.
• propertyNames - use this when you want to set more than 1 property in the ValueHolder object. Example: assume you want to set not only the "zipCode" property, but also the "city", "state" and "country" properties, use setPropertyNames(new String[] {"zipCode","city","state","country"})
• listPropertyNames - set the to the source property name(s) in the list objects. IMPORTANT - The name(s) of the listPropertyNames properties MUST be in the same ORDER as the propertyName(s). The names in the listPropertNames may be different than the names in the propertyNames since they are associated with in objects in the list, not the valueHolder. Example: Given a list containing "Location" objects which has properties "zipCode", "cityName", "stateAbbr", and "country", for a single property use setListPropertyNames(new String[] {"zipCode"}). For multiple properties use setListPropertyNames(new String[] {"zipCode", "cityName", "stateAbbr", "country"})

  If the list is an ObjectArrayValueHolder, then the property name should always be a single "value" (which is the default).

Other Important Information

When a selection is made, the values are copied from the properties in the list to the properties in the valueHolder object. The property names in propertyNames[] and listPropertyNames[] must appear in a corresponding order.

A "null" item will always be added to the displayOptionList. When the "null" item is selected, a null will be assigned to the propertyNames[] in the valueHolder object. The actual "null" item to to display is defined by the nullDisplay (default is "--none--").

The format and formatPattern govern the display property in this component. The getText method returns the formatted display property, while the setText method changes the current selection to one whose display matches the given value. If you attempt to setText for an item that is not in the list, a NotInListException will be thrown.

Constructor Summary

SelectField()
Constructs a new SelectField.

SelectField(int javaDataType)
Creates a new SelectField of the given data type.

SelectField(int javaDataType, java.lang.Object[] array)
Constructs a new SelectField of the given data type with the given list of options.

SelectField(java.lang.Object[] array)
Constructs a new SelectField with the given list of options.

Method Summary

protected TextModel	createDefaultModel() Creates the default TextModel used by this component By default, this method returns a new DefaultSelectModel.
protected TextModel	createDefaultModel(int javaDataType) Creates the default model of given data type used by this component
protected SelectFieldRenderer	createDefaultRenderer() Creates the default SelectFieldRenderer for this component.
java.lang.String	getDisplayPropertyName() Returns the property name of the list object to display in the list.
CollectionValueHolder	getList() Returns collectionValueHolder which holds the collection of possible selections.
java.lang.String[]	getListPropertyNames() Returns array of property names in list object to copy to valueHolder object.
java.lang.String	getNullDisplay() Returns value to display in list for a null value.
java.lang.String	getPropertyName() Gets the property name in valueHolder that will hold the value from the list.
java.lang.String[]	getPropertyNames() Sets array of property names in valueHolder object that correspond to properties of list object.
SelectFieldRenderer	getRenderer() Returns the renderer subcomponent used to render the value to the Document.
java.lang.Object	getSelection() Gets the current selection from the Model.
protected SelectModel	getSelectModel() Returns the current model cast as a SelectModel
java.lang.String	getText() Returns the model value as a String (using Format if defined).
boolean	isNullAllowed() Returns indicator that a null value is a valid selection.
void	processRenderEvent(RenderEvent e) Responds to a render event for this component.
void	setDisplayPropertyName(java.lang.String newDisplayPropertyName) Sets the property name of the list object to display in the list.
void	setList(CollectionValueHolder newList) Sets collectionValueHolder which holds the collection of possible selections.
void	setListPropertyNames(java.lang.String[] newListPropertyNames) Sets array of property names in list object to copy to valueHolder object.
void	setModel(TextModel newModel) Sets the Model for this component to the given SelectModel.
void	setNullAllowed(boolean nullAllowed) Sets indicator that a null value is a valid selection.
void	setNullDisplay(java.lang.String newNullDisplay) Sets value to display in list for a null value.
void	setPropertyName(java.lang.String newPropertyName) Sets the property name in valueHolder that will hold the value from the list.
void	setPropertyNames(java.lang.String[] newPropertyNames) Sets array of property names in valueHolder object that correspond to properties of list object.
void	setRenderer(SelectFieldRenderer newRenderer) Sets the renderer subcomponent used to render the value to the Document.
void	setSelection(java.lang.Object value) Sets the current selection from the Model.
void	setText(java.lang.String text) Sets the model value from the given String (using Format if defined).

Methods inherited from class com.taursys.xml.AbstractField

addAttribute, addNotify, addTextNode, createAttribute, createAttribute, createAttribute, createBoundAttribute, createBoundTextNode, createTextNode, createTextNode, createTextNode, getAttribute, getAttributeName, getAttributeText, getAttributeValue, getElementDelegate, getId, getTextNode, getTextNodeText, getTextNodeValue, isEarlyInputNotify, processInputEvent, removeAttribute, removeAttribute, removeNotify, removeTextNode, removeTextNode, setAttributeName, setAttributeText, setAttributeValue, setEarlyInputNotify, setId, setTextNodeText, setTextNodeValue, setValueHolder, toString

Methods inherited from class com.taursys.xml.Parameter

getDefaultValue, getFormat, getFormatPattern, getModel, getParameter, getValue, getValueHolder, processParameterEvent, setDefaultValue, setFormat, setFormatPattern, setParameter, setValue

Methods inherited from class com.taursys.xml.Component

addEventType, addInputListener, addParameterListener, addRecycleListener, addRenderListener, addTriggerListener, dispatchEvent, fireActionPerformed, fireInputReceived, fireParameterReceived, fireRecycle, fireRender, getEventTypeList, getParent, isNotifySet, isVisible, lazyAddNotify, lazyRemoveNotify, processEvent, processRecycleEvent, processTriggerEvent, removeEventType, removeInputListener, removeParameterListener, removeRecycleListener, removeRenderListener, removeTriggerListener, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SelectField

public SelectField()

Constructs a new SelectField.

SelectField

public SelectField(int javaDataType)

Creates a new SelectField of the given data type.

Parameters:

javaDataType - the data type for the VariantValueHolder

See Also:

for defined data type constants TYPE_XXXXXX.

SelectField

public SelectField(java.lang.Object[] array)

Constructs a new SelectField with the given list of options.

SelectField

public SelectField(int javaDataType,
                   java.lang.Object[] array)

Constructs a new SelectField of the given data type with the given list of options.

Parameters:

javaDataType - the data type for the VariantValueHolder

array - the array of options

See Also:

for defined data type constants TYPE_XXXXXX.

Method Detail

createDefaultModel

protected TextModel createDefaultModel()

Creates the default TextModel used by this component By default, this method returns a new DefaultSelectModel. Override this method to define your own TextModel.

Overrides:

createDefaultModel in class Parameter

createDefaultModel

protected TextModel createDefaultModel(int javaDataType)

Creates the default model of given data type used by this component

Overrides:

createDefaultModel in class Parameter

Parameters:

javaDataType - data type for new model

See Also:

for defined data type constants TYPE_XXX.

setModel

public void setModel(TextModel newModel)
              throws java.lang.IllegalArgumentException

Sets the Model for this component to the given SelectModel. Although this component allows passing a TextModel, the given model must be an instanceof SelectModel.

Overrides:

setModel in class Parameter

Parameters:

newModel - to be used by this component.

Throws:

java.lang.IllegalArgumentException - if newModel is not instance of SelectModel

getSelectModel

protected SelectModel getSelectModel()

Returns the current model cast as a SelectModel

createDefaultRenderer

protected SelectFieldRenderer createDefaultRenderer()

Creates the default SelectFieldRenderer for this component. By default, this method returns a new SelectFieldRenderer. Override this method to define your own SelectFieldRenderer.

setRenderer

public void setRenderer(SelectFieldRenderer newRenderer)

Sets the renderer subcomponent used to render the value to the Document.

getRenderer

public SelectFieldRenderer getRenderer()

Returns the renderer subcomponent used to render the value to the Document.

getText

public java.lang.String getText()
                         throws ModelException

Returns the model value as a String (using Format if defined). This method simply calls the getText method in the model.

Overrides:

getText in class Parameter

Throws:

ModelException

setText

public void setText(java.lang.String text)
             throws ModelException

Sets the model value from the given String (using Format if defined). This method simply calls the setText method in the model.

Overrides:

setText in class Parameter

Throws:

ModelException

getSelection

public java.lang.Object getSelection()
                              throws ModelException

Gets the current selection from the Model. This method simply invokes the model's getSelectedItem method.

Throws:

ModelException

setSelection

public void setSelection(java.lang.Object value)
                  throws ModelException

Sets the current selection from the Model. This method simply invokes the model's setSelectedItem method.

Throws:

ModelException

processRenderEvent

public void processRenderEvent(RenderEvent e)
                        throws RenderException

Responds to a render event for this component. This uses the renderer subcomponent to actually render the value. It first notifies any RenderListeners of the event. It then invokes the renderer subcomponent to render the value to the document.

Specified by:

processRenderEvent in class AbstractField

Parameters:

e - the current render event message

Throws:

RenderException - if problem rendering value to document

setList

public void setList(CollectionValueHolder newList)

Sets collectionValueHolder which holds the collection of possible selections.

getList

public CollectionValueHolder getList()

Returns collectionValueHolder which holds the collection of possible selections.

setDisplayPropertyName

public void setDisplayPropertyName(java.lang.String newDisplayPropertyName)

Sets the property name of the list object to display in the list. Default is "value".

getDisplayPropertyName

public java.lang.String getDisplayPropertyName()

Returns the property name of the list object to display in the list. Default is "value".

setListPropertyNames

public void setListPropertyNames(java.lang.String[] newListPropertyNames)

Sets array of property names in list object to copy to valueHolder object. Default is {"value"}.

getListPropertyNames

public java.lang.String[] getListPropertyNames()

Returns array of property names in list object to copy to valueHolder object. Default is {"value"}.

setPropertyNames

public void setPropertyNames(java.lang.String[] newPropertyNames)

Sets array of property names in valueHolder object that correspond to properties of list object. Default is {"value"}.

getPropertyNames

public java.lang.String[] getPropertyNames()

Sets array of property names in valueHolder object that correspond to properties of list object. Default is {"value"}.

setPropertyName

public void setPropertyName(java.lang.String newPropertyName)

Sets the property name in valueHolder that will hold the value from the list. If you have also used the setPropertyNames method, then this will change the first name in that array.

Overrides:

setPropertyName in class Parameter

getPropertyName

public java.lang.String getPropertyName()

Gets the property name in valueHolder that will hold the value from the list. If you have also used the setPropertyNames method, then this will return the first name in that array.

Overrides:

getPropertyName in class Parameter

setNullAllowed

public void setNullAllowed(boolean nullAllowed)

Sets indicator that a null value is a valid selection. If true, the nullDisplay value will appear in the list of options generated by getDisplayOptionList and setText will accept null or the nullDisplay value. If false, the setText method will throw a NotInListException if null or the nullDisplay value is set, and the nullDisplay will not appear in the displayOptionList. Default is true.

isNullAllowed

public boolean isNullAllowed()

Returns indicator that a null value is a valid selection. If true, the nullDisplay value will appear in the list of options generated by getDisplayOptionList and setText will accept null or the nullDisplay value. If false, the setText method will throw a NotInListException if null or the nullDisplay value is set, and the nullDisplay will not appear in the displayOptionList. Default is true.

setNullDisplay

public void setNullDisplay(java.lang.String newNullDisplay)

Sets value to display in list for a null value.

getNullDisplay

public java.lang.String getNullDisplay()

Returns value to display in list for a null value.