net.sf.click.control
Class FieldSet

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

All Implemented Interfaces:

Container, Control, Serializable

public class FieldSet

extends AbstractContainer

Provides a FieldSet container control: <fieldset>.

FieldSet

Card Name*
Card Number*	VisaMasterAmExDinersDiscover
Expiry*

FieldSet provides a container for laying out form Field controls.

One can use FieldSet with both Form and BasicForm, however the behavior of FieldSet differs for each.

• BasicForm - when adding FieldSet to a BasicForm, it will behave exactly like a normal container. The fields will be rendered next to each other in the order they were added to the fieldset.
• Form - When adding FieldSet to a Form, FieldSet will delegate rendering to Form.renderFieldSet(net.sf.click.util.HtmlStringBuffer, net.sf.click.control.FieldSet) thus using the properties of its parent Form for laying out and rendering of its fields.

  A FieldSet can contain any Control, however when used in conjuction with Form, it is recommended to only add fields since Form's auto-layout is geared towards the layout of fields.

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 BasicForm	form The parent BasicForm.
protected String	label The FieldSet label.
protected String	legend The FieldSet legend.
protected Map	legendAttributes The FieldSet legend attributes map.
protected boolean	showBorder The render the fieldset border flag, default value is true.

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

controlMap, controls

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

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's width in columns.
int	getColumns() Return the number of fieldset layout table columns.
List	getFieldList() Return the List of fields, ordered in addition order 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.
BasicForm	getForm() Return the parent Form containing the FieldSet or null if no form is present in the parent hierarchy.
String	getHtmlImports() Return the HTML head import statements for contained fields.
String	getLabel() Return the fieldSet display label.
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	hasLegendAttributes() Return true if the fieldset has attributes or false otherwise.
Control	insert(Control control, int index) Add a Field to the FieldSet and return the added instance.
boolean	onProcess() Process the request invoking onProcess() on the contained Control elements.
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	renderContent(HtmlStringBuffer buffer) Render this container content to the specified buffer.
protected void	renderTagBegin(String tagName, HtmlStringBuffer buffer) Render the tag and common attributes.
void	setColumns(int columns) Set the number of fieldset layout table columns.
void	setForm(BasicForm form) Set the FieldSet's the parent Form.
void	setLabel(String label) Set the Field display caption.
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	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.AbstractContainer

add, contains, getControl, getControlMap, getControls, getControlSizeEst, hasControls, onDestroy, onInit, onRender, renderChildren, renderTagEnd

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

addStyleClass, appendAttributes, getActionListener, getAttribute, getAttributes, getContext, getId, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasStyles, onDeploy, registerActionEvent, removeStyleClass, setActionListener, setAttribute, setId, setName, setParent, 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.

form

protected BasicForm form

The parent BasicForm.

label

protected String label

The FieldSet label.

legend

protected String legend

The FieldSet legend.

legendAttributes

protected Map legendAttributes

The FieldSet legend attributes map.

showBorder

protected boolean showBorder

The render the 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 and return the added instance.

Please note if the FieldSet's parent is a Form, the Fields inside the FieldSet will be laid out by the Form.

Specified by:

insert in interface Container

Overrides:

insert in class AbstractContainer

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, if the control's parent is a Page 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. The field will be added to AbstractContainer.getControlMap() using its name.

Field instances will be add to AbstractContainer.getControls().

Parameters:

field - the field to add to the form

Returns:

the field added to this form

Throws:

IllegalArgumentException - if the field is null, the field name is not defined, the fieldSet already contains a control with the same name or if the field's parent is a Page

See Also:

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

add

public Field add(Field field,
                 int width)

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

Note HiddenFields 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's name is not defined, a HiddenField, the fieldset already contains a control with the same name, if the field's parent is a Page 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

Overrides:

remove in class AbstractContainer

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

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

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

getFieldList

public List getFieldList()

Return the List of fields, ordered in addition order 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

getForm

public BasicForm getForm()

Return the parent Form containing the FieldSet or null if no form is present in the parent hierarchy.

Returns:

the parent Form containing the FieldSet

setForm

public void setForm(BasicForm form)

Set the FieldSet's the parent Form.

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 AbstractContainer

Returns:

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

See Also:

Control.getHtmlImports()

getLabel

public String getLabel()

Return the fieldSet display label.

Returns:

the display label of the Field

See Also:

Field.getLabel()

setLabel

public void setLabel(String label)

Set the Field display caption.

Parameters:

label - the display label of the Field

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 AbstractContainer

Returns:

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

See Also:

Control.onProcess().

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 AbstractControl

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)

render

public void render(HtmlStringBuffer buffer)

Render the HTML representation of the FieldSet.

If FieldSet is contained within a Form instance, this method will delegate rendering to Form.renderFieldSet(net.sf.click.util.HtmlStringBuffer, net.sf.click.control.FieldSet).

The size of buffer is determined by AbstractContainer.getControlSizeEst().

Specified by:

render in interface Control

Overrides:

render in class AbstractContainer

Parameters:

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

See Also:

AbstractControl.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 AbstractContainer.getControlSizeEst().

Overrides:

toString in class AbstractContainer

Returns:

the HTML representation of this control

See Also:

Object.toString()

renderTagBegin

protected void renderTagBegin(String tagName,
                              HtmlStringBuffer buffer)

Description copied from class: AbstractControl

Render the tag and common attributes.

Please note: the tag will not be closed by this method. This enables callers of this method to append extra attributes as needed.

For example the result of calling:

 Field field = new TextField("mytext");
 HtmlStringBuffer buffer = new HtmlStringBuffer();
 field.renderTagBegin("div", buffer);
 

will be:

 <div name="mytext" id="mytext"
 

Note that the tag is not closed.

Overrides:

renderTagBegin in class AbstractControl

Parameters:

tagName - the name of the tag to render

buffer - the buffer to append the output to

See Also:

AbstractControl.renderTagBegin(java.lang.String, net.sf.click.util.HtmlStringBuffer)

renderContent

protected void renderContent(HtmlStringBuffer buffer)

Description copied from class: AbstractContainer

Render this container content to the specified buffer.

Overrides:

renderContent in class AbstractContainer

Parameters:

buffer - the buffer to append the output to

See Also:

AbstractContainer.renderContent(net.sf.click.util.HtmlStringBuffer)