com.taursys.html
Class HTMLCheckBox

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

All Implemented Interfaces:

DocumentComponent, Element, MapperComponent

public class HTMLCheckBox

extends CheckboxField

HTMLCheckBox is a peer component to an HTML input type checkbox. This field is for a stand-alone checkbox and maintains its checked/unchecked state.

This component uses an HTMLCheckboxFieldRenderer to render its value. If the CheckboxModel isSelected returns true, then the renderer adds the "checked" attribute to the input tag, otherwise it removed the attribute.

The HTML checkbox has a unique behavior in that it only sends a value if it is checked. It does not send anything back if it is un-checked. This behavior requires the use of a defaultValue or uncheckedValue.

The unselectedValue is used as the defaultValue for this component. If the unselectedValue is not null it will be used during parameter or input dispatching whenever the checkbox is NOT checked (no parameter is sent). In that case, the unselectedValue will be used as the value for the InputEvent.

Limitation: Since input processing will ALWAYS set the value to either the selectedValue (if input present) or unselectedValue (if no input is present), you will want to disable input processing when simply preseting or displaying values. With an HTML checkbox, there is no way to distinguish between an unchecked box or no input submission. To disable input processing, either set the ServletForm's enableInput property to false, or temporarily set the HTMLCheckBox's parameter property to null or blank.

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

HTMLCheckBox()
Constructs a new HTMLCheckBox

HTMLCheckBox(int javaDataType)
Constructs a new HTMLCheckBox for the given data type

Method Summary

protected CheckboxFieldRenderer	createDefaultRenderer() Creates the default CheckboxFieldRenderer for this component.
java.lang.String	getDefaultValue() Get the both the defaultValue and the unselectedValue for this component.
void	setDefaultValue(java.lang.String newDefaultValue) Set the both the defaultValue and the unselectedValue for this component.

Methods inherited from class com.taursys.xml.CheckboxField

createDefaultModel, createDefaultModel, getCheckboxModel, getRenderer, getSelectedValue, getText, getUnselectedValue, isSelected, processRenderEvent, setModel, setRenderer, setSelected, setSelectedValue, setText, setUnselectedValue

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

getFormat, getFormatPattern, getModel, getParameter, getPropertyName, getValue, getValueHolder, processParameterEvent, 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

HTMLCheckBox

public HTMLCheckBox()

Constructs a new HTMLCheckBox

HTMLCheckBox

public HTMLCheckBox(int javaDataType)

Constructs a new HTMLCheckBox for the given data type

Parameters:

javaDataType - data type for component value

See Also:

DataTypes

Method Detail

createDefaultRenderer

protected CheckboxFieldRenderer createDefaultRenderer()

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

Overrides:

createDefaultRenderer in class CheckboxField

setDefaultValue

public void setDefaultValue(java.lang.String newDefaultValue)

Set the both the defaultValue and the unselectedValue for this component. The defaultValue and unselectedValue are the same for this component. If the defaultValue is not null it will be used during parameter dispatching whenever the expected parameter is NOT present in the input. In that case, the defaultValue will be used as the value for the InputEvent.

The HTML input type checkbox only sends a value if the box is checked, and NO value is sent if it is unchecked. Therfore the defaultValue is used to provide the input for the "unchecked" state.

Overrides:

setDefaultValue in class Parameter

Parameters:

newDefaultValue - to be used if no input is received.

getDefaultValue

public java.lang.String getDefaultValue()

Get the both the defaultValue and the unselectedValue for this component. The defaultValue and unselectedValue are the same for this component. If the defaultValue is not null it will be used during parameter dispatching whenever the expected parameter is NOT present in the input. In that case, the defaultValue will be used as the value for the InputEvent.

The HTML input type checkbox only sends a value if the box is checked, and NO value is sent if it is unchecked. Therfore the defaultValue is used to provide the input for the "unchecked" state.

Overrides:

getDefaultValue in class Parameter

Returns:

default value to be used if no input is received.