com.taursys.xml
Class CheckboxField

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

All Implemented Interfaces:

DocumentComponent, Element, MapperComponent

Direct Known Subclasses:

HTMLCheckBox

public class CheckboxField

extends AbstractField

This component is used to display and change a "selected indicator". This component uses a DefaultCheckboxModel to manage the state. There are only two states for this component: selected or not-selected.

To use this component you must first set the the following properties as indicated:

• selectedValue - the text value which indicates a "selected" state. The default value is "true".
• unselectedValue - the text value which indicates an "un-selected" state. The default value is "" (blank) which will result in a null value being stored in the valueHolder

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 input type checkbox, use the HTMLCheckBox 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 DefaultCheckboxModel. You can change this by overriding the createDefaultModel method or explicitly setting the model property.

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

Un-bound Mode

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

• selectedValue - the text value which indicates a "selected" state. The default value is "true".
• unselectedValue - the text value which indicates an "un-selected" state. The default value is "" (blank) which will result in a null value being stored in the valueHolder

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 bound to the ValueHolder which contains the current selected state and is to be updated if the state is changed.
• propertyName - set this to the property name (belonging to the object in the ValueHolder) which will be bound to the selected state. Example: given a ValueHolder with an "Address" object which has a "active" property, use setPropertyName("active") to store the current selected state in the "Address.active" property.

Version:

1.0

Author:

Marty Phelan

Constructor Summary

CheckboxField()
Constructs a new CheckboxField with a default model and renderer.

CheckboxField(int javaDataType)
Constructs a new CheckboxField for the given datatype with a default model and renderer.

Method Summary

protected TextModel	createDefaultModel() Creates the default TextModel used by this component By default, this method returns a new DefaultCheckboxModel.
protected TextModel	createDefaultModel(int javaDataType) Creates the default model of given data type used by this component
protected CheckboxFieldRenderer	createDefaultRenderer() Creates the default CheckboxFieldRenderer for this component.
protected CheckboxModel	getCheckboxModel() Returns the current model cast as a SelectModel
CheckboxFieldRenderer	getRenderer() Returns the renderer subcomponent used to render the value to the Document.
java.lang.String	getSelectedValue() Get the value used to indicate a selected state.
java.lang.String	getText() Returns the model value as a String (using Format if defined).
java.lang.String	getUnselectedValue() Get the value used to indicate an unselected state.
boolean	isSelected() Gets the current selected state from the Model.
void	processRenderEvent(RenderEvent e) Responds to a render event for this component.
void	setModel(TextModel newModel) Sets the Model for this component to the given CheckboxModel.
void	setRenderer(CheckboxFieldRenderer newRenderer) Sets the renderer subcomponent used to render the value to the Document.
void	setSelected(boolean newSelected) Sets the current state as selected(true) or unselected(false) for the model.
void	setSelectedValue(java.lang.String newSelectedValue) Set the value used to indicate a selected state.
void	setText(java.lang.String text) Sets the model value from the given String (using Format if defined).
void	setUnselectedValue(java.lang.String newUnselectedValue) Set the value used to indicate an unselected state.

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, getPropertyName, getValue, getValueHolder, processParameterEvent, setDefaultValue, setFormat, setFormatPattern, setParameter, setPropertyName, 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

CheckboxField

public CheckboxField()

Constructs a new CheckboxField with a default model and renderer. The default model, a DefaultCheckboxModel, is created via the createDefaultModel method in the Parameter superclass. The default renderer, a CheckboxFieldRenderer, is created via the createDefaultRenderer method.

CheckboxField

public CheckboxField(int javaDataType)

Constructs a new CheckboxField for the given datatype with a default model and renderer. The default model, a DefaultCheckboxModel, is created via the createDefaultModel method in the Parameter superclass. The default renderer, a CheckboxFieldRenderer, is created via the createDefaultRenderer method.

Parameters:

javaDataType - data type for new model

See Also:

for defined data type constants TYPE_XXX.

Method Detail

createDefaultModel

protected TextModel createDefaultModel()

Creates the default TextModel used by this component By default, this method returns a new DefaultCheckboxModel. 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 CheckboxModel. Although this component allows passing a TextModel, the given model must be an instanceof CheckboxModel.

Overrides:

setModel in class Parameter

Parameters:

newModel - to be used by this component.

Throws:

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

getCheckboxModel

protected CheckboxModel getCheckboxModel()

Returns the current model cast as a SelectModel

createDefaultRenderer

protected CheckboxFieldRenderer createDefaultRenderer()

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

setRenderer

public void setRenderer(CheckboxFieldRenderer newRenderer)

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

getRenderer

public CheckboxFieldRenderer 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

isSelected

public boolean isSelected()
                   throws ModelException

Gets the current selected state from the Model. This method simply invokes the model's isSelected method.

Throws:

UnknownStateValueException - if the internal value does not match a known state text value.

ModelException - if problem while setting properties of object in valueHolder.

setSelected

public void setSelected(boolean newSelected)
                 throws ModelException

Sets the current state as selected(true) or unselected(false) for the model.

Throws:

ModelException - if problem while setting properties of object in valueHolder.

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

setSelectedValue

public void setSelectedValue(java.lang.String newSelectedValue)

Set the value used to indicate a selected state.

Parameters:

newSelectedValue - the value used to indicate a selected state.

getSelectedValue

public java.lang.String getSelectedValue()

Get the value used to indicate a selected state.

Returns:

the value used to indicate a selected state.

setUnselectedValue

public void setUnselectedValue(java.lang.String newUnselectedValue)

Set the value used to indicate an unselected state.

Parameters:

newUnselectedValue - the value used to indicate a unselected state.

getUnselectedValue

public java.lang.String getUnselectedValue()

Get the value used to indicate an unselected state.

Returns:

the value used to indicate a unselected state.