fc.web.forms

Class ChoiceGroup

java.lang.Object

fc.web.forms.Field

fc.web.forms.ChoiceGroup

Direct Known Subclasses:

CheckboxGroup, RadioGroup

public abstract class ChoiceGroup
extends Field

Abstracts a HTML grouped choice element type such as choicebox or radio.

This class allows for grouped fields i.e., more than 1 form fields having the same name. The main difference between a choicebox and a radio group is that only 1 item can be selected within a radio group whereas choiceboxes allow multiple selections within the group.

There are 3 different kinds of choice groups (and their concrete subclasses).

ChoiceGroup

A normal choice group that is created/instantiated and added to the form. This select displays the same options to all users and these options cannot be changed per request/user (since it does not implement the setValue(FormData fd, ...) method. This field will always track that the submitted data is a legal value and was not hacked/modified by the client.

RefreshableChoiceGroup

This select starts out by displaying the same options to all users. However, it allows options to be thereafter set/displayed per user/request. If per user/request options are shown, then the user can modify/hack/send any option. The field itself won't track this and applicaiton logic is responsible (if applicable) for tracking if the submitted data is valid.

DependentChoiceGroup

This select is similar to a RefreshableSelect but uses an external dependency class to set both it's initial values and per user/request subsequent values. The dependency typically looks at other fields in the form to generate this data.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ChoiceGroup.Choice Creates a new choice for this choice group.

Nested classes/interfaces inherited from class fc.web.forms.Field

Field.Type

Constructor Summary

Constructors

Constructor and Description
ChoiceGroup(String name) Creates a new grouped choice object that intitially contains no choice fields
ChoiceGroup(String name, List choices) Creates a new grouped choice object that intitially contains the specified choices.

Method Summary

Modifier and Type	Method and Description
void	add(ChoiceGroup.Choice choice)
void	addAll(ChoiceGroup cg) Adds all the elements of the specified choice group to this choice group.
Map	getAllElements() Returns a map containing ChoiceGroup.Choice all elements contained within this group.
ChoiceGroup.Choice	getChoice(int n) Returns the choice specified by the index n.
abstract Field.Type	getType() Subclasses should return an appropriate Field.Type.
Collection	getValue(FormData fd) Returns a Collection containing the choices selected by the user.
boolean	isFilled(FormData fd) Returns true if some option has been selected by the user, false otherwise.
boolean	isSelected(FormData fd, ChoiceGroup.Choice choice, boolean default_val) Returns true is the specified choice was selected by the user (the user's submission is provided by the formdata argument).
void	renderImpl(FormData fd, Writer writer) Renders all elements of this group one after onether, seperated by a whitespace.
void	renderImpl(FormData fd, Writer writer, String prefix, String suffix) Renders the elements of this form by prefixing and suffixing each element with the specified arguments.
void	reset() Clears all values in this group.
void	reverseRender(boolean val) If called with true, renders the choices contained in this group in the reverse order in which they were added (by default, choices are rendered in the order they were added)
void	setValue(Collection values) Sets the values for this choice group.
void	setValue(FormData fd, Collection values) Sets the selected values for this choicegroup in the specified form data.
void	setValueFromSubmit(FormData fd, javax.servlet.http.HttpServletRequest req) This method sets the value of this field from the parameters obtained from the specified request.
String	toString()
void	writeLabel(boolean val) Utility methods that calls the ChoiceGroup.Choice.writeLabel method for each choice contained in this group

Methods inherited from class fc.web.forms.Field

add, addError, addLabel, addString, disable, disable, enable, enable, getLabel, getName, getValidateErrors, isEnabled, render, render, render, renderError, renderError, renderStyleTag, setStyleTag, validate

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ChoiceGroup

public ChoiceGroup(String name)

Creates a new grouped choice object that intitially contains no choice fields

Parameters:

name - the field name

ChoiceGroup

public ChoiceGroup(String name,
                   List choices)

Creates a new grouped choice object that intitially contains the specified choices.

Parameters:

name - the field name

choices - a list of ChoiceGroup.Choice objects.

Method Detail

getType

public abstract Field.Type getType()

Description copied from class: Field

Subclasses should return an appropriate Field.Type. This type is rendered as part of <input type= ...

Specified by:

getType in class Field

add

public void add(ChoiceGroup.Choice choice)

addAll

public void addAll(ChoiceGroup cg)

Adds all the elements of the specified choice group to this choice group.

Throws:

IllegalArgumentException - if the specified choicegrop was null or is the same choicegroup as the source.

getValue

public Collection getValue(FormData fd)

Returns a Collection containing the choices selected by the user. Each item in this collection is of type ChoiceGroup.Choice. If there are no selected options, returns an empty unmodifiable collection.

Parameters:

fd - the submited form data

setValue

public void setValue(FormData fd,
                     Collection values)

Sets the selected values for this choicegroup in the specified form data. The choices in the choicegroup are not set by this method, only which of the choices that will be displayed as selected/not-selected for the request associated with the form data.

To set the choices themselves, use the appropriate constructor or call the setValue(Collection) method. .The specified form data must not be null.

Parameters:

fd - the non-null form data object for rendering the form

values - a collection of ChoiceGroup.Choice objects

setValue

public void setValue(Collection values)

Sets the values for this choice group. Any previously set values are first cleared before new values are set.

Parameters:

values - a collection of ChoiceGroup.Choice objects

getChoice

public ChoiceGroup.Choice getChoice(int n)

Returns the choice specified by the index n. The choices are indexed in the order that they were added to the form. (regardless of whether this field is being reverse rendered).

Throws:

IndexOutOfBoundsException - if the specified index is out of range.

isFilled

public boolean isFilled(FormData fd)

Returns true if some option has been selected by the user, false otherwise. (also returns false is the specified form data is null).

Specified by:

isFilled in class Field

setValueFromSubmit

public void setValueFromSubmit(FormData fd,
                               javax.servlet.http.HttpServletRequest req)
                        throws SubmitHackedException

Description copied from class: Field

This method sets the value of this field from the parameters obtained from the specified request. The name of the parameter to obtain this value will typically be the name of this field itself.

Specified by:

setValueFromSubmit in class Field

Parameters:

fd - the form data object to store the value in

Throws:

SubmitHackedException

reverseRender

public void reverseRender(boolean val)

If called with true, renders the choices contained in this group in the reverse order in which they were added (by default, choices are rendered in the order they were added)

renderImpl

public void renderImpl(FormData fd,
                       Writer writer)
                throws IOException

Renders all elements of this group one after onether, seperated by a whitespace. For more control over rendering spacing and direction, use the Field.render(FormData, Writer, String, String) method. It's also possible to render each item in a group individually by not calling this method but getting a Map/List of elements in this group and rendering them in whichever location desired. (by calling render on each specific choice itself).

Specify null for the formdata if rendering this element for the first time (before it has been submitted to by the user).

Specified by:

renderImpl in class Field

Throws:

IOException

renderImpl

public void renderImpl(FormData fd,
                       Writer writer,
                       String prefix,
                       String suffix)
                throws IOException

Renders the elements of this form by prefixing and suffixing each element with the specified arguments.

Parameters:

writer - the output destination

prefix - prefix value for each element. specify null or an empty string if not needed.

suffix - suffix value for each element. specify null or an empty string if not needed.

Throws:

IOException

reset

public void reset()

Clears all values in this group.

getAllElements

public Map getAllElements()

Returns a map containing ChoiceGroup.Choice all elements contained within this group. This is useful if the elements need to be rendered individually for custom positioning on an html page.

Each elements in the map will reflect the original selection state when it was created. Each element can optionally be checked to see if it was selected by the user by calling the isSelected(fc.web.forms.FormData, fc.web.forms.ChoiceGroup.Choice, boolean) method.

isSelected

public boolean isSelected(FormData fd,
                          ChoiceGroup.Choice choice,
                          boolean default_val)

Returns true is the specified choice was selected by the user (the user's submission is provided by the formdata argument).

Parameters:

fd - form data submitted by user (can be null)

choice - a choice option belonging to this group

default_val - the default value to return in case the form data was null or did not contain this choicegroup. This will typically be false or choice.isOrigSelected()

writeLabel

public void writeLabel(boolean val)

Utility methods that calls the ChoiceGroup.Choice.writeLabel method for each choice contained in this group

toString

public String toString()

Overrides:

toString in class Field