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.

  • Constructor Details

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

    • 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(java.util.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, jakarta.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(FormData, 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