org.apache.click.control
Class FieldSet

java.lang.Object
  extended by org.apache.click.control.AbstractControl
      extended by org.apache.click.control.Field
          extended by 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
*
*
*
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:

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