net.sf.click.control
Class FieldSet

java.lang.Object
  extended bynet.sf.click.control.AbstractControl
      extended bynet.sf.click.control.Field
          extended bynet.sf.click.control.FieldSet
All Implemented Interfaces:
Container, Control, Serializable

public class FieldSet
extends Field
implements Container

Provides a FieldSet container control:   <fieldset>.

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