org.apache.click.control
Class FieldSet

java.lang.Object
  org.apache.click.control.AbstractControl
      org.apache.click.control.Field
          org.apache.click.control.FieldSet

All Implemented Interfaces:

Serializable, Control, Container, Stateful

public class FieldSet
extends Field
implements Container

Provides a FieldSet container control: <fieldset>.

FieldSet

Card Name*
Card Number*	VisaMasterAmExDinersDiscover
Expiry*

FieldSet provides a container for laying out form Field controls.

FieldSet Example

An FieldSet example containing credit card payment details is provided below:

 public class PaymentDetails() {

     public Form form = new Form();

     public PaymentDetails() {
         FieldSet paymentFieldSet = new FieldSet("paymentDetails");
         form.add(paymentFieldSet);

         paymentFieldSet.add(new TextField("cardName", true));
         paymentFieldSet.add(new CreditCardField("cardNumber", true));
         IntegerField expiryField = new IntegerField("expiry", true);
         expiryField.setSize(4);
         expiryField.setMaxLength(4);
         paymentFieldSet.add(expiryField);

         form.add(new Submit("ok", "    OK    ", this, "onOkClick");
         form.add(new Submit("  Cancel  ", this, "onCancelClick"));
     }
 } 

When the FieldSet is processed it invokes the onProcess() method of its contained Fields. Beyond this the FieldSet performs no server side processing, and should be considered simply as a container for laying out form fields.

See also the W3C HTML reference: FIELDSET

See Also:

Serialized Form

Field Summary

protected Integer	columns This property serves as a hint to the number of table columns the fieldset is rendered with.
protected Map<String,Control>	controlMap The map of controls keyed by field name.
protected List<Control>	controls The list of controls.
protected List<Field>	fieldList The ordered list of fields, excluding buttons.
protected Map<String,Integer>	fieldWidths The map of field width values.
protected String	legend The FieldSet legend.
protected Map<String,String>	legendAttributes The FieldSet legend attributes map.
protected boolean	showBorder The render fieldset border flag, default value is true.

Fields inherited from class org.apache.click.control.Field

disabled, error, focus, form, help, label, labelStyle, labelStyleClass, parentStyleClassHint, parentStyleHint, readonly, required, tabindex, title, trim, validate, value

Fields inherited from class org.apache.click.control.AbstractControl

actionListener, attributes, behaviors, headElements, listener, listenerMethod, messages, name, parent, styles

Fields inherited from interface org.apache.click.Control

CONTROL_MESSAGES

Constructor Summary

FieldSet()
Create a FieldSet with no name defined.

FieldSet(String name)
Create a FieldSet with the given name.

FieldSet(String name, String legend)
Create a FieldSet with the given name and legend.

Method Summary

Control	add(Control control) Add a Control to the fieldset and return the added instance.
Control	add(Control control, int width) Add the control to the fieldset and specify the control's width in columns.
Field	add(Field field) Add the field to the fieldSet, and set the fields form property.
Field	add(Field field, int width) Add the field to the fieldset and specify the field width in columns.
boolean	contains(Control control) Return true if the container contains the specified control.
int	getColumns() Return the number of fieldset layout table columns.
Control	getControl(String controlName) Return the named control from the container if found or null otherwise.
protected Map<String,Control>	getControlMap() Return the map of controls where each map's key / value pair will consist of the control name and instance.
List<Control>	getControls() Return the sequential list of controls held by the container.
protected int	getControlSizeEst() Return the estimated rendered control size in characters.
Field	getField(String name) Return the named field if contained in the fieldset, or null if not found.
List<Field>	getFieldList() Return the ordered list of FieldSet fields, excluding buttons.
Map<String,Control>	getFields() Return the Map of fieldset fields, keyed on field name.
Map<String,Integer>	getFieldWidths() Return the map of field width values, keyed on field name.
String	getLegend() Return the fieldset Legend element value: <legend> If the legend value is null, this method will attempt to find a localized label message in the parent messages using the key: getName() + ".title" If not found then the message will be looked up in the /click-control.properties file using the same key.
String	getLegendAttribute(String name) Return the legend HTML attribute with the given name, or null if the attribute does not exist.
Map<String,String>	getLegendAttributes() Return the fieldset attributes Map.
boolean	getShowBorder() Return the render fieldset border flag.
Object	getState() Return the FieldSet state.
String	getTag() Return the fieldset's html tag: fieldset.
boolean	hasControls() Returns true if this container has existing controls, false otherwise.
boolean	hasLegendAttributes() Return true if the fieldset has attributes or false otherwise.
Control	insert(Control control, int index) Add a Field to the FieldSet at the specified index and return the added instance.
boolean	isDisabled() Return true if the FieldSet is disabled.
boolean	isReadonly() Return true if the FieldSet is readonly.
void	onDestroy() This method does nothing.
void	onInit() This method does nothing.
boolean	onProcess() Process the request invoking onProcess() on the contained Control elements.
void	onRender() This method does nothing.
boolean	remove(Control control) Remove the given control from the container, returning true if the control was found in the container and removed, or false if the control was not found.
void	remove(Field field) Remove the given field from the fieldset.
boolean	removeField(String name) Remove the named field from the fieldset, returning true if removed or false if not found.
void	removeState(Context context) Remove the FieldSet state from the session for the given request context.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the FieldSet.
protected void	renderButtons(HtmlStringBuffer buffer) Render the fieldset buttons to the string buffer.
protected void	renderFields(HtmlStringBuffer buffer) Render the fieldset's form fields to the string buffer.
Control	replace(Control currentControl, Control newControl) Deprecated. this method was used for stateful pages, which have been deprecated
void	restoreState(Context context) Restore the FieldSet state from the session for the given request context.
void	saveState(Context context) Save the FieldSet state to the session for the given request context.
void	setColumns(int columns) Set the number of fieldset layout table columns.
void	setDisabled(boolean disabled) Set the FieldSet disabled flag which in turn will disable all its fields.
void	setForm(Form form) Set the FieldSet's the parent Form.
void	setLegend(String legend) Set the fieldset Legend element value: <legend>.
void	setLegendAttribute(String name, String value) Set the fieldset HTML attribute with the given attribute name and value.
void	setReadonly(boolean readonly) Set the FieldSet readonly flag which in turn will set all its fields to readonly.
void	setShowBorder(boolean value) Set the render fieldset border flag.
void	setState(Object state) Set the FieldSet state.
String	toString() Returns the HTML representation of the FieldSet.

Methods inherited from class org.apache.click.control.Field

bindRequestValue, getError, getErrorLabel, getFocus, getFocusJavaScript, getForm, getHelp, getId, getLabel, getLabelStyle, getLabelStyleClass, getParentStyleClassHint, getParentStyleHint, getRequestValue, getTabIndex, getTextAlign, getTitle, getValidate, getValidationJavaScript, getValue, getValueObject, getWidth, isHidden, isRequired, isTrim, isValid, renderTagBegin, setError, setErrorMessage, setErrorMessage, setFocus, setHelp, setLabel, setLabelStyle, setLabelStyleClass, setListener, setParent, setParentStyleClassHint, setParentStyleHint, setRequired, setTabIndex, setTextAlign, setTitle, setTrim, setValidate, setValue, setValueObject, setWidth, validate

Methods inherited from class org.apache.click.control.AbstractControl

addBehavior, addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getHeadElements, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, removeBehavior, removeStyleClass, renderTagEnd, setActionListener, setAttribute, setId, setName, setStyle

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.click.Control

getBehaviors, getContext, getHeadElements, getId, getMessages, getName, getParent, hasBehaviors, isAjaxTarget, onDeploy, setListener, setName, setParent

Field Detail

controls

protected List<Control> controls

The list of controls.

controlMap

protected Map<String,Control> controlMap

The map of controls keyed by field name.

fieldList

protected final List<Field> fieldList

The ordered list of fields, excluding buttons.

fieldWidths

protected Map<String,Integer> fieldWidths

The map of field width values.

legend

protected String legend

The FieldSet legend.

legendAttributes

protected Map<String,String> legendAttributes

The FieldSet legend attributes map.

showBorder

protected boolean showBorder

The render fieldset border flag, default value is true.

columns

protected Integer columns

This property serves as a hint to the number of table columns the fieldset is rendered with.

Currently only Form acts upon this property.

Constructor Detail

FieldSet

public FieldSet(String name)

Create a FieldSet with the given name.

Parameters:

name - the fieldset name element value

FieldSet

public FieldSet(String name,
                String legend)

Create a FieldSet with the given name and legend.

Parameters:

name - the fieldset name

legend - the fieldset legend element value

FieldSet

public FieldSet()

Create a FieldSet with no name defined.

Please note the control's name must be defined before it is valid.

Method Detail

insert

public Control insert(Control control,
                      int index)

Add a Field to the FieldSet at the specified index and return the added instance.

Please note: if the FieldSet contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

Controls can be retrieved from the Map controlMap where the key is the Control name and value is the Control instance.

All controls are available on the controls list at the index they were inserted. If you are only interested in Fields, note that fields are available on fieldList.

The specified index only applies to controls, not fieldList.

Please note if the specified control already has a parent assigned, it will automatically be removed from that parent and inserted into the fieldSet.

Specified by:

insert in interface Container

Parameters:

control - the control to add to the FieldSet and return

index - the index at which the control is to be inserted

Returns:

the control that was added to the FieldSet

Throws:

IllegalArgumentException - if the control is null, the Field's name is not defined or if the control is neither a Field nor FieldSet

See Also:

Container.insert(org.apache.click.Control, int)

replace

public Control replace(Control currentControl,
                       Control newControl)

Deprecated. this method was used for stateful pages, which have been deprecated

Replace the current control with the new control.

Specified by:

replace in interface Container

Parameters:

currentControl - the current control container in the fieldset

newControl - the control to replace the current control

Returns:

the new control that replaced the current control

Throws:

IllegalArgumentException - if the currentControl or newControl is null

IllegalStateException - if the currentControl is not contained in the fieldset

add

public Control add(Control control)

Add a Control to the fieldset and return the added instance.

Please note: if the FieldSet contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

Controls can be retrieved from the Map controlMap where the key is the Control name and value is the Control instance.

All controls are available on the controls list in the order they were added. If you are only interested in Fields, note fields are available on fieldList.

Specified by:

add in interface Container

Parameters:

control - the control to add to the container and return

Returns:

the control that was added to the container

Throws:

IllegalArgumentException - if the control is null, the Field's name is not defined or if the control is neither a Field nor FieldSet

See Also:

Container.add(org.apache.click.Control).

add

public Field add(Field field)

Add the field to the fieldSet, and set the fields form property.

Please note: if the FieldSet contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

Fields can be retrieved from the Map fields where the key is the Field name and value is the Field instance.

Fields are available on fieldList.

Parameters:

field - the field to add to the fieldSet

Returns:

the field added to this fieldSet

Throws:

IllegalArgumentException - if the field is null or the field name is not defined

See Also:

add(org.apache.click.Control)

add

public Field add(Field field,
                 int width)

Add the field to the fieldset and specify the field width in columns.

Please note: if the FieldSet contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

Fields can be retrieved from the Map fields where the key is the Field name and value is the Field instance.

Fields are available on fieldList.

Note Button and HiddenField types are not valid arguments for this method.

Parameters:

field - the field to add to the fieldset

width - the width of the field in table columns

Returns:

the field added to this fieldset

Throws:

IllegalArgumentException - if the field is null, field name is not defined, field is a Button or HiddenField or the width < 1

add

public Control add(Control control,
                   int width)

Add the control to the fieldset and specify the control's width in columns.

Please note: if the FieldSet contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

Controls can be retrieved from the Map controlMap where the key is the Control name and value is the Control instance.

Controls are available on the controls list.

Note Button and HiddenField types are not valid arguments for this method.

Parameters:

control - the control to add to the fieldSet

width - the width of the control in table columns

Returns:

the control added to this fieldSet

Throws:

IllegalArgumentException - if the control is null, control is a Button or HiddenField or the width < 1

remove

public boolean remove(Control control)

Description copied from interface: Container

Remove the given control from the container, returning true if the control was found in the container and removed, or false if the control was not found.

Specified by:

remove in interface Container

Parameters:

control - the control to remove from the container

Returns:

true if the control was removed from the container

Throws:

IllegalArgumentException - if the control is null

See Also:

Container.remove(org.apache.click.Control)

remove

public void remove(Field field)

Remove the given field from the fieldset.

Parameters:

field - the field to remove from the fieldset

Throws:

IllegalArgumentException - if the field is null

removeField

public boolean removeField(String name)

Remove the named field from the fieldset, returning true if removed or false if not found.

Parameters:

name - the name of the field to remove from the fieldset

Returns:

true if the named field was removed or false otherwise

getControls

public List<Control> getControls()

Description copied from interface: Container

Return the sequential list of controls held by the container.

Specified by:

getControls in interface Container

Returns:

the sequential list of controls held by the container

See Also:

Container.getControls()

getControl

public Control getControl(String controlName)

Description copied from interface: Container

Return the named control from the container if found or null otherwise.

Specified by:

getControl in interface Container

Parameters:

controlName - the name of the control to get from the container

Returns:

the named control from the container if found or null otherwise

See Also:

Container.getControl(java.lang.String)

contains

public boolean contains(Control control)

Description copied from interface: Container

Return true if the container contains the specified control.

Specified by:

contains in interface Container

Parameters:

control - the control whose presence in this container is to be tested

Returns:

true if the container contains the specified control

See Also:

Container.contains(org.apache.click.Control)

hasControls

public boolean hasControls()

Returns true if this container has existing controls, false otherwise.

Specified by:

hasControls in interface Container

Returns:

true if the container has existing controls, false otherwise.

See Also:

AbstractContainer.hasControls()

getTag

public String getTag()

Return the fieldset's html tag: fieldset.

Overrides:

getTag in class AbstractControl

Returns:

this controls html tag

See Also:

AbstractControl.getTag()

isDisabled

public boolean isDisabled()

Return true if the FieldSet is disabled. The FieldSet will also be disabled if the parent Form is disabled.

Important Note: disabled fieldset also disables all its fields which will not submit their values in a HTML form POST. This may cause validation issues in a form submission. Please note this is a HTML limitation and is not due to Click.

Overrides:

isDisabled in class Field

Returns:

true if the Field is disabled

See Also:

Field.setDisabled(boolean)

setDisabled

public void setDisabled(boolean disabled)

Set the FieldSet disabled flag which in turn will disable all its fields.

Important Note: disabled fieldset also disables all its fields which will not submit their values in a HTML form POST. This may cause validation issues in a form submission. Please note this is a HTML limitation and is not due to Click.

Overrides:

setDisabled in class Field

Parameters:

disabled - the Field disabled flag

isReadonly

public boolean isReadonly()

Return true if the FieldSet is readonly. The FieldSet will also be readonly if the parent Form is readonly.

Overrides:

isReadonly in class Field

Returns:

true if the FieldSet is a readonly

setReadonly

public void setReadonly(boolean readonly)

Set the FieldSet readonly flag which in turn will set all its fields to readonly.

Overrides:

setReadonly in class Field

Parameters:

readonly - the FieldSet readonly flag

getColumns

public int getColumns()

Return the number of fieldset layout table columns. This property supplies a hint to the number of table columns the fieldset should be rendered with.

Note currently only Form acts upon the column value.

By default this property inherits its value from the parent Form, but can be specified to override the form value.

Returns:

the number of fieldset layout table columns

setColumns

public void setColumns(int columns)

Set the number of fieldset layout table columns. This property supplies a hint to the number of table columns the fieldset should be rendered with.

Note currently only Form acts upon the column value.

Parameters:

columns - the number of fieldset layout table columns

getShowBorder

public boolean getShowBorder()

Return the render fieldset border flag. The border is the HTML <fieldset> element.

Returns:

the render the fieldset border flag

setShowBorder

public void setShowBorder(boolean value)

Set the render fieldset border flag. The border is the HTML <fieldset> element.

Parameters:

value - the render the fieldset border flag

getField

public Field getField(String name)

Return the named field if contained in the fieldset, or null if not found.

Parameters:

name - the name of the field

Returns:

the named field if contained in the fieldset

getFieldList

public List<Field> getFieldList()

Return the ordered list of FieldSet fields, excluding buttons.

The order of the fields is the same order they were added to the FieldSet.

The returned list only includes fields directly added to the FieldSet.

Returns:

the ordered List of fieldset fields

getFields

public Map<String,Control> getFields()

Return the Map of fieldset fields, keyed on field name.

Returns:

the Map of fieldset fields, keyed on field name

getFieldWidths

public Map<String,Integer> getFieldWidths()

Return the map of field width values, keyed on field name.

Returns:

the map of field width values, keyed on field name

setForm

public void setForm(Form form)

Set the FieldSet's the parent Form.

Overrides:

setForm in class Field

Parameters:

form - FieldSet's parent Form

getLegend

public String getLegend()

Return the fieldset Legend element value: <legend>

If the legend value is null, this method will attempt to find a localized label message in the parent messages using the key:

getName() + ".title"

If not found then the message will be looked up in the /click-control.properties file using the same key. If a value cannot be found in the parent or control messages then the FieldSet name will be converted into a legend using the ClickUtils.toLabel(String) method.

Returns:

the fieldset Legend element value

setLegend

public void setLegend(String legend)

Set the fieldset Legend element value: <legend>. If the legend value is a zero length string no legend element will be rendered. You can set a blank zero length string if you want to render the fieldset border but don't want a legend caption.

Parameters:

legend - the fieldset Legend element value

getLegendAttribute

public String getLegendAttribute(String name)

Return the legend HTML attribute with the given name, or null if the attribute does not exist.

Parameters:

name - the name of legend HTML attribute

Returns:

the legend HTML attribute

setLegendAttribute

public void setLegendAttribute(String name,
                               String value)

Set the fieldset HTML attribute with the given attribute name and value.

Parameters:

name - the name of the form HTML attribute

value - the value of the form HTML attribute

Throws:

IllegalArgumentException - if name parameter is null

getLegendAttributes

public Map<String,String> getLegendAttributes()

Return the fieldset attributes Map.

Returns:

the fieldset attributes Map

hasLegendAttributes

public boolean hasLegendAttributes()

Return true if the fieldset has attributes or false otherwise.

Returns:

true if the fieldset has attributes on false otherwise

onProcess

public boolean onProcess()

Process the request invoking onProcess() on the contained Control elements.

Specified by:

onProcess in interface Control

Overrides:

onProcess in class Field

Returns:

true if all Controls were processed, or false if any Control returned false

See Also:

Control.onProcess()

onDestroy

public void onDestroy()

Description copied from class: AbstractControl

This method does nothing. Subclasses may override this method to perform clean up any resources.

Specified by:

onDestroy in interface Control

Overrides:

onDestroy in class AbstractControl

See Also:

Control.onDestroy()

onInit

public void onInit()

Description copied from class: AbstractControl

This method does nothing. Subclasses may override this method to perform initialization.

Specified by:

onInit in interface Control

Overrides:

onInit in class AbstractControl

See Also:

Control.onInit()

onRender

public void onRender()

Description copied from class: AbstractControl

This method does nothing. Subclasses may override this method to perform pre rendering logic.

Specified by:

onRender in interface Control

Overrides:

onRender in class AbstractControl

See Also:

Control.onRender()

getState

public Object getState()

Return the FieldSet state. The following state is returned:

• all the input Field values and other FieldSets contained in this FieldSet and child containers.

Specified by:

getState in interface Stateful

Overrides:

getState in class Field

Returns:

the state of input Fields and FieldSets contained in this FieldSet

setState

public void setState(Object state)

Set the FieldSet state. The state will be applied to all the input Fields and FieldSets contained in the FieldSet or child containers.

Specified by:

setState in interface Stateful

Overrides:

setState in class Field

Parameters:

state - the FieldSet state to set

render

public void render(HtmlStringBuffer buffer)

Render the HTML representation of the FieldSet.

The size of buffer is determined by getControlSizeEst().

Specified by:

render in interface Control

Overrides:

render in class AbstractControl

Parameters:

buffer - the specified buffer to render the control's output to

See Also:

Control.render(org.apache.click.util.HtmlStringBuffer)

removeState

public void removeState(Context context)

Remove the FieldSet state from the session for the given request context.

Overrides:

removeState in class Field

Parameters:

context - the request context

See Also:

saveState(org.apache.click.Context), restoreState(org.apache.click.Context)

restoreState

public void restoreState(Context context)

Restore the FieldSet state from the session for the given request context.

This method delegates to setState(java.lang.Object) to set the field restored state.

Overrides:

restoreState in class Field

Parameters:

context - the request context

See Also:

saveState(org.apache.click.Context), removeState(org.apache.click.Context)

saveState

public void saveState(Context context)

Save the FieldSet state to the session for the given request context.

* This method delegates to getState() to retrieve the field state to save.

Overrides:

saveState in class Field

Parameters:

context - the request context

See Also:

restoreState(org.apache.click.Context), removeState(org.apache.click.Context)

toString

public String toString()

Returns the HTML representation of the FieldSet.

The rendering of the FieldSet is delegated to render(org.apache.click.util.HtmlStringBuffer). The size of buffer is determined by getControlSizeEst().

Overrides:

toString in class AbstractControl

Returns:

the HTML representation of this control

See Also:

Object.toString()

getControlMap

protected Map<String,Control> getControlMap()

Return the map of controls where each map's key / value pair will consist of the control name and instance.

Returns:

the map of controls

See Also:

AbstractContainer.getControlMap()

getControlSizeEst

protected int getControlSizeEst()

Description copied from class: AbstractControl

Return the estimated rendered control size in characters.

Overrides:

getControlSizeEst in class AbstractControl

Returns:

the estimated rendered control size in characters

See Also:

AbstractControl.getControlSizeEst()

renderFields

protected void renderFields(HtmlStringBuffer buffer)

Render the fieldset's form fields to the string buffer. This method will apply the parent Forms properties to the layout and rendering of fields.

Parameters:

buffer - the StringBuffer to render to

renderButtons

protected void renderButtons(HtmlStringBuffer buffer)

Render the fieldset buttons to the string buffer.

Parameters:

buffer - the StringBuffer to render to