fc.web.forms
Class Select

java.lang.Object
  extended by fc.web.forms.Field
      extended by fc.web.forms.Select
Direct Known Subclasses:
RefreshableSelect

public class Select
extends Field

An HTML Select field

There are 3 different kinds of selects:

Select
A normal select 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.
RefreshableSelect
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 browser can modify/hack/send any option. This field (in contrast to most other fields in the form) itself won't track this and application logic is responsible (if applicable) for tracking if the submitted data is valid.
.
DependentSelect
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
static class Select.Option
          Represents an option in the selection list
 
Nested classes/interfaces inherited from class fc.web.forms.Field
Field.Type
 
Constructor Summary
Select(String name)
          Creates a new select element with no initial values.
Select(String name, List values)
          Creates a new select element with the specified initial values and no multiple selections allowed.
 
Method Summary
 void add(Select.Option opt)
          Adds a new option to the selection list.
 void add(String item)
          Adds a new option to the selection list.
 Select allowMultiple(boolean allow)
          true is multiple selections are allowed, false otherwise.
 boolean getBooleanValue(FormData fd)
          Convenience method that returns the single value of this field as a boolean.
 int getIntValue(FormData fd)
          Convenience method that returns the single value of this field as a Integer.
 String getStringValue(FormData fd)
          Convenience method that returns the selected option as a String.
 Field.Type getType()
          Subclasses should return an appropriate Field.Type.
 List getValue(FormData fd)
          Returns a List containing the selected options.
 boolean isFilled(FormData fd)
          Returns true if some option has been selected by the user, false otherwise.
static List makeOptionsFromQuery(Connection con, String query)
          Uses the first column as the option text and if there is a second column uses it as the corresponding option value.
static List makeOptionsFromQuery(Connection con, String query, Select.Option defaultOption)
          Uses the first column as the option text and if there is a second column uses it as the corresponding option value.
 void renderImpl(FormData fd, Writer writer)
           
 void reset()
          Clears all data in this select.
 Select setSize(int size)
          This value (if set) is rendered as the html SIZE tag.
 void setValue(List values)
          Sets the values for this select.
 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.
 Select useQuery(Connection con, String query)
          Convenience method that calls useQuery(con, query, null).
 Select useQuery(Connection con, String query, Select.Option defaultOpt)
          The specified query is used to populate this select.
 
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, toString, validate
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Select

public Select(String name)
Creates a new select element with no initial values. Multiple selections are not initially allowed.

Parameters:
name - the field name

Select

public Select(String name,
              List values)
Creates a new select element with the specified initial values and no multiple selections allowed. There is no explicit default selection which typically means the browser will show the first item in the list as the selection item.

Parameters:
name - the field name
values - the initial option values for this class. The objects contained in the list must be of type Select.Option otherwise a ClassCastException may be thrown in future operations on this object.
Throws:
IllegalArgumentException - if the values parameter was null (note: an empty but non-null List is ok)
Method Detail

useQuery

public Select useQuery(Connection con,
                       String query,
                       Select.Option defaultOpt)
                throws SQLException
The specified query is used to populate this select. The default parameter (if not null) is the default selected option. If the default option is null, no option is selected for multiple-value selects and the first option returned by the query is selected for single-value selects.

Typically, this method may be invoked like:

useQuery(con, "select id, name from my_lookup_table", new Option("--choose--"));
If the lookup table has more than 2 columns, the query can look like (in standard SQL syntax):
useQuery(con, "select id, name1 || ' ' || name2 from my_lookup_table", new Option("--choose--"));
This shows columns name1 and name2 concatenated with each other.

Parameters:
con - the connection to use for the query. This connection is not closed by this method. Close this connection from the calling code to prevent connection leaks.
Returns:
this select for method chaining convenience
Throws:
SQLException

useQuery

public Select useQuery(Connection con,
                       String query)
                throws SQLException
Convenience method that calls useQuery(con, query, null).

Throws:
SQLException

makeOptionsFromQuery

public static List makeOptionsFromQuery(Connection con,
                                        String query)
                                 throws SQLException
Uses the first column as the option text and if there is a second column uses it as the corresponding option value.

Throws:
SQLException

makeOptionsFromQuery

public static List makeOptionsFromQuery(Connection con,
                                        String query,
                                        Select.Option defaultOption)
                                 throws SQLException
Uses the first column as the option text and if there is a second column uses it as the corresponding option value. Uses an additional default option.

Throws:
SQLException

getType

public 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

setValue

public void setValue(List values)
Sets the values for this select. Any previously set values are first cleared before new values are set.

Note, to show user specific options via FormData, use a RefreshableSelect instead.

Parameters:
values - a list of Select.Option objects

getValue

public List getValue(FormData fd)
Returns a List containing the selected options. Each object in the collection will be of type Select.Option. If there are no selected options, the returned list will be an empty list.

Parameters:
fd - the submited form data. This object should not be null otherwise a NPE will be thrown.

getStringValue

public String getStringValue(FormData fd)
Convenience method that returns the selected option as a String. No guarantees are made as to which selection is returned when more than one selection is selected (this method is really meant for when the select only allows single selections as a dropdown).

The returned value is of type String obtained by called the selected Option's Select.Option.getValue() method.

If there is no selection, returns null


getIntValue

public int getIntValue(FormData fd)
Convenience method that returns the single value of this field as a Integer.

All the caveats of #getSingleValueAsString() apply.

Throws:
NumberFormatException - if the value could not be returned as in integer.

getBooleanValue

public boolean getBooleanValue(FormData fd)
Convenience method that returns the single value of this field as a boolean.

All the caveats of #getSingleValueAsString() apply. In particular, the formdata should contain non-null data with at least one selection.


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

renderImpl

public void renderImpl(FormData fd,
                       Writer writer)
                throws IOException
Specified by:
renderImpl in class Field
Throws:
IOException

add

public void add(Select.Option opt)
Adds a new option to the selection list. Replaces any previous option that was added previously with the same value.

Parameters:
opt - the option to be added

add

public void add(String item)
Adds a new option to the selection list. Replaces any previous option that was added previously with the same value. This method will have the same effect as if the add(new Select.Option(item)) method was invoked.

Parameters:
item - the option to be added

reset

public void reset()
Clears all data in this select.


setSize

public Select setSize(int size)
This value (if set) is rendered as the html SIZE tag. If the list contains more options than specified by size, the browser will display the selection list with scrollbars.

Returns:
this object for method chaining convenience

allowMultiple

public Select allowMultiple(boolean allow)
true is multiple selections are allowed, false otherwise. This value (if set) is rendered as the html MULTIPLE tag.

Returns:
this object for method chaining convenience