net.sf.click.control
Class FieldSet

java.lang.Object
  net.sf.click.control.AbstractControl
      net.sf.click.control.Field
          net.sf.click.control.FieldSet

All Implemented Interfaces:

Container, Control, Serializable

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

Author:

Malcolm Edgar

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	fieldWidths The map of field width values.
protected String	legend The FieldSet legend.
protected Map	legendAttributes The FieldSet legend attributes map.
protected boolean	showBorder The render fieldset border flag, default value is true.

Fields inherited from class net.sf.click.control.Field

disabled, error, focus, form, help, label, readonly, required, tabindex, title, validate, value

Fields inherited from class net.sf.click.control.AbstractControl

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

Fields inherited from interface net.sf.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	getControlMap() Return the map of controls where each map's key / value pair will consist of the control name and instance.
List	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	getFieldList() Return the List of fields in the same order they were added to the fieldset.
Map	getFields() Return the Map of fieldset fields, keyed on field name.
Map	getFieldWidths() Return the map of field width values, keyed on field name.
String	getHtmlImports() Return the HTML head import statements for contained fields.
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	getLegendAttributes() Return the fieldset attributes Map.
boolean	getShowBorder() Return the render fieldset border flag.
String	getTag() Return the fieldsets'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() The on destroy request event handler.
void	onInit() The on initialize event handler.
boolean	onProcess() Process the request invoking onProcess() on the contained Control elements.
void	onRender() The on render event handler.
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	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 fieldsets form fields to the string buffer.
void	setActionListener(ActionListener actionListener) This method is not supported and will throw a UnsupportedOperationException.
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	setListener(Object listener, String method) This method is not supported and will throw a UnsupportedOperationException.
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.
String	toString() Returns the HTML representation of the FieldSet.

Methods inherited from class net.sf.click.control.Field

bindRequestValue, getError, getErrorLabel, getFocus, getFocusJavaScript, getForm, getHelp, getId, getLabel, getRequestValue, getTabIndex, getTextAlign, getTitle, getValidate, getValidationJavaScript, getValue, getValueObject, getWidth, isHidden, isRequired, isValid, setError, setErrorMessage, setErrorMessage, setErrorMessage, setErrorMessage, setFocus, setHelp, setLabel, setParent, setRequired, setTabIndex, setTextAlign, setTitle, setValidate, setValue, setValueObject, setWidth, validate

Methods inherited from class net.sf.click.control.AbstractControl

addStyleClass, appendAttributes, getActionListener, getAttribute, getAttributes, getContext, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasStyles, onDeploy, registerActionEvent, removeStyleClass, renderTagBegin, renderTagEnd, 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 net.sf.click.Control

getContext, getId, getMessages, getName, getParent, onDeploy, setName, setParent

Field Detail

fieldWidths

protected Map fieldWidths

The map of field width values.

legend

protected String legend

The FieldSet legend.

legendAttributes

protected Map 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.

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, the container already contains a control with the same name or if the control is neither a Field nor FieldSet

See Also:

Container.add(net.sf.click.Control)

add

public Control add(Control control)

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

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, the container already contains a control with the same name or if the control is neither a Field nor FieldSet

See Also:

Container.add(net.sf.click.Control).

add

public Field add(Field field)

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

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, the field name is not defined or the fieldSet already contains a control with the same name

See Also:

add(net.sf.click.Control)

add

public Field add(Field field,
                 int width)

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

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, the fieldset already contains a field with the same name 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.

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, the fieldSet already contains a control with the same name 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(net.sf.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 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(net.sf.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 fieldsets'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

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

Return the List of fields in 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 getFields()

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

Returns:

the Map of fieldset fields, keyed on field name

getFieldWidths

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

getHtmlImports

public String getHtmlImports()

Return the HTML head import statements for contained fields.

Specified by:

getHtmlImports in interface Control

Overrides:

getHtmlImports in class AbstractControl

Returns:

the HTML head import statements for the contained field stylesheet and JavaScript files

See Also:

Control.getHtmlImports()

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

onDestroy

public void onDestroy()

Description copied from interface: Control

The on destroy request event handler. Control classes should use this method to add any resource clean up code.

This method is guaranteed to be called before the Page object reference goes out of scope and is available for garbage collection.

Container implementations should recursively invoke the onDestroy method on each of their child controls ensuring that all controls receive this event.

Please note: a common problem when overriding onDestroy in subclasses is forgetting to call super.onDestroy(). Consider carefully whether you should call super.onDestroy() or not, especially for Containers which by default call onDestroy on all their child controls as well.

Specified by:

onDestroy in interface Control

Overrides:

onDestroy in class AbstractControl

See Also:

Control.onDestroy()

onInit

public void onInit()

Description copied from interface: Control

The on initialize event handler. Each control will be initialized before its Control.onProcess() method is called.

Container implementations should recursively invoke the onInit method on each of their child controls ensuring that all controls receive this event.

Please note: a common problem when overriding onInit in subclasses is forgetting to call super.onInit(). Consider carefully whether you should call super.onInit() or not, especially for Containers which by default call onInit on all their child controls as well.

Specified by:

onInit in interface Control

Overrides:

onInit in class Field

See Also:

Control.onInit()

onRender

public void onRender()

Description copied from interface: Control

The on render event handler. This event handler is invoked prior to the control being rendered, and is useful for providing pre rendering logic.

The on render method is typically used to populate tables performing some database intensive operation. By putting the intensive operations in the on render method they will not be performed if the user navigates away to a different page.

Container implementations should recursively invoke the onRender method on each of their child controls ensuring that all controls receive this event.

Please note: a common problem when overriding onRender in subclasses is forgetting to call super.onRender(). Consider carefully whether you should call super.onRender() or not, especially for Containers which by default call onRender on all their child controls as well.

Specified by:

onRender in interface Control

Overrides:

onRender in class AbstractControl

See Also:

Control.onRender()

setListener

public void setListener(Object listener,
                        String method)

This method is not supported and will throw a UnsupportedOperationException.

Specified by:

setListener in interface Control

Overrides:

setListener in class Field

Parameters:

listener - the listener object with the named method to invoke

method - the name of the method to invoke

See Also:

Control.setListener(Object, String)

setActionListener

public void setActionListener(ActionListener actionListener)

This method is not supported and will throw a UnsupportedOperationException.

Overrides:

setActionListener in class AbstractControl

Parameters:

actionListener - the control's action listener

See Also:

AbstractControl.setActionListener(ActionListener)

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(net.sf.click.util.HtmlStringBuffer)

toString

public String toString()

Returns the HTML representation of the FieldSet.

The rendering of the FieldSet is delegated to render(net.sf.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 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 fieldsets 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