net.sf.click.control
Class Select

java.lang.Object
  net.sf.click.control.AbstractControl
      net.sf.click.control.Field
          net.sf.click.control.Select

All Implemented Interfaces:

Control, Serializable

public class Select

extends Field

Provides a Select control: <select></select>.

Select

Option 1 Option 2 Option 3

The Control listener will be invoked if the Select is valid and an item(s) is selected by the user.

Select Examples

Single Item Select

A single item Select, will only allow users to select one item from the list. By default the Select multiple item property is false.

If a Select is required, an item after the first in the list must be selected for the Field to be valid. This forces the user to make an active selection. An example of a single item Select is provided below along with the rendered HTML.

 public class GenderPage extends Page {

     public Form form = new Form();

     private Select genderSelect = new Select("Gender");

     public GenderPage() {
         genderSelect.setRequired(true);
         genderSelect.add(new Option("U", "");
         genderSelect.add(new Option("M", "Male"));
         genderSelect.add(new Option("F", "Female"));
         form.add(genderSelect);

         form.add(new Submit("ok", "  OK  "));
     }

     public void onPost() {
         if (form.isValid()) {
             String gender = genderSelect.getValue();
             ..
         }
     }
 } 

Rendered HTML:

Gender*	MaleFemale

Note how Option items are added to the Select. In this example the "U" option will not be a valid selection, as it is the first item in the option list.

Multiple Item Select

A multiple item Select, will allow users to select multiple items from the list. By default the Select multiple item property is false, and must be enabled for multiple item selects.

If multiple item Select is required, the user must select an item(s) in the list for the Field to be valid. A valid selection can include any item including the first item.

An example of a single item Select is provided below along with the rendered HTML.

 public class LocationPage extends Page {

     public Form form = new Form();

     private Select locationSelect = new Select("location");

     public LocationPage() {
         locationSelect.setMutliple(true);
         locationSelect.setRequired(true);
         locationSelect.setSize(7);
         locationSelect.add("QLD");
         locationSelect.add("NSW");
         locationSelect.add("NT");
         locationSelect.add("SA");
         locationSelect.add("TAS");
         locationSelect.add("VIC");
         locationSelect.add("WA");
         form.add(locationSelect);

         form.add(new Submit("ok", "  OK  "));
     }

     public void onPost() {
         if (form.isValid()) {
             String location = locationSelect.getValue();
             ..
         }
     }
 } 

Rendered HTML:

Location*	QLDNSWNTSATASVICWA

Note in this example the add(String) method is used to add an Option item to the Select.

Specify a default value

It is often necessary to set a default selected value. This is best done in the Page.onRender() method:

 public MyPage extends Page {
     private Select mySelect;

     public MyPage() {
         mySelect = new Select("mySelect");
         mySelect.add("YES");
         mySelect.add("NO");
     }

     public void onRender() {
         // Only specify a default value if the current value is null
         if (mySelect.getValue() == null) {
             mySelect.setValue("YES");
         }
     }
 }
 

Readonly Behaviour

Note the <select> HTML element does not support the "readonly" attribute. To provide readonly style behaviour, the Select control will render the "disabled" attribute when it is readonly to give the appearance of a readonly field, and will render a hidden field of the same name so that its value will be submitted with the form.

See also the W3C HTML reference: SELECT

Author:

Malcolm Edgar

See Also:

Option, OptionGroup, Serialized Form

Field Summary

protected boolean	multiple The multiple options selectable flag.
protected List	optionList The Select Option/OptionGroup list.
protected List	selectedValues The multiple selected values.
protected int	size The Select display size in rows.
protected static String	VALIDATE_SELECT_FUNCTION The field validation JavaScript function template.

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

disabled, error, focus, form, help, label, readonly, required, tabindex, title, validate, value

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

Select()
Create a Select field with no name defined.

Select(String name)
Create a Select field with the given name.

Select(String name, boolean required)
Create a Select field with the given name and required status.

Select(String name, String label)
Create a Select field with the given name and label.

Select(String name, String label, boolean required)
Create a Select field with the given name, label and required status.

Method Summary

void	add(Option option) Add the given Option to the Select.
void	add(OptionGroup optionGroup) Add the given OptionGroup to the Select.
void	add(String value) Add the given option value to the Select.
void	addAll(Collection options) Add the given Option/OptionGroup/String/Number/Boolean collection to the Select.
void	addAll(Collection objects, String value, String label) Add the given collection of objects to the Select, creating new Option instances based on the object properties specified by value and label.
void	addAll(Map options) Add the given Map of option values and labels to the Select.
void	addAll(String[] options) Add the given array of string options to the Select option list.
void	bindRequestValue() Bind the request submission, setting the Field.value or selectedValues property if defined in the request.
int	getControlSizeEst() Return the estimated rendered control size in characters.
List	getMultipleValues() Deprecated. use getSelectedValues() instead, this method will be removed in subsequent releases
List	getOptionList() Return the Option list.
List	getSelectedValues() Return the list of selected values.
int	getSize() Return the number of Select display rows.
String	getTag() Return the select's html tag: select.
String	getValidationJavaScript() Return the Select JavaScript client side validation function.
boolean	isMultiple() Return true if multiple options can be selected.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the Select.
protected void	setInitialValue() Set the initial select option value.
void	setMultiple(boolean value) Set the multiple options can be selected flag.
void	setMultipleValues(List multipleValues) Deprecated. use getSelectedValues() instead, this method will be removed in subsequent releases
void	setOptionList(List options) Set the Option list.
void	setSelectedValues(List multipleValues) Set the list of selected values.
void	setSize(int rows) Set the number of the Select display rows.
void	validate() Validate the Select request submission.

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

getError, getErrorLabel, getFocus, getFocusJavaScript, getForm, getHelp, getId, getLabel, getRequestValue, getTabIndex, getTextAlign, getTitle, getValidate, getValue, getValueObject, getWidth, isDisabled, isHidden, isReadonly, isRequired, isValid, onInit, onProcess, setDisabled, setError, setErrorMessage, setErrorMessage, setErrorMessage, setErrorMessage, setFocus, setForm, setHelp, setLabel, setListener, setParent, setReadonly, setRequired, setTabIndex, setTextAlign, setTitle, setValidate, setValue, setValueObject, setWidth

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

addStyleClass, appendAttributes, getActionListener, getAttribute, getAttributes, getContext, getHtmlImports, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasStyles, onDeploy, onDestroy, onRender, registerActionEvent, removeStyleClass, renderTagBegin, renderTagEnd, setActionListener, setAttribute, setId, setName, setStyle, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VALIDATE_SELECT_FUNCTION

protected static final String VALIDATE_SELECT_FUNCTION

The field validation JavaScript function template. The function template arguments are:

• 0 - is the field id
• 1 - is the Field required status
• 2 - is the localized error message
• 3 - is the default Select option value

See Also:

Constant Field Values

multiple

protected boolean multiple

The multiple options selectable flag. The default value is false.

optionList

protected List optionList

The Select Option/OptionGroup list.

size

protected int size

The Select display size in rows. The default size is one.

selectedValues

protected List selectedValues

The multiple selected values. This list will only be populated if multiple is true.

Constructor Detail

Select

public Select(String name)

Create a Select field with the given name.

Parameters:

name - the name of the field

Select

public Select(String name,
              String label)

Create a Select field with the given name and label.

Parameters:

name - the name of the field

label - the label of the field

Select

public Select(String name,
              boolean required)

Create a Select field with the given name and required status.

Parameters:

name - the name of the field

required - the field required status

Select

public Select(String name,
              String label,
              boolean required)

Create a Select field with the given name, label and required status.

Parameters:

name - the name of the field

label - the label of the field

required - the field required status

Select

public Select()

Create a Select field with no name defined.

Please note the control's name must be defined before it is valid.

Method Detail

getTag

public String getTag()

Return the select's html tag: select.

Overrides:

getTag in class AbstractControl

Returns:

this controls html tag

See Also:

AbstractControl.getTag()

add

public void add(Option option)

Add the given Option to the Select.

Parameters:

option - the Option value to add

Throws:

IllegalArgumentException - if option is null

add

public void add(OptionGroup optionGroup)

Add the given OptionGroup to the Select.

Parameters:

optionGroup - the OptionGroup value to add

Throws:

IllegalArgumentException - if optionGroup is null

add

public void add(String value)

Add the given option value to the Select. This covenience method will create a new Option with the given value and add it to the Select. The new Option display label will be the same as its value.

Parameters:

value - the option value to add

Throws:

IllegalArgumentException - if the value is null

addAll

public void addAll(Collection options)

Add the given Option/OptionGroup/String/Number/Boolean collection to the Select.

Parameters:

options - the collection of Option/OptionGroup/String/Number/Boolean objects to add

Throws:

IllegalArgumentException - if options is null, or the collection contains an unsupported class

addAll

public void addAll(Map options)

Add the given Map of option values and labels to the Select. The Map entry key will be used as the option value and the Map entry value will be used as the option label.

It is recommended that LinkedHashMap is used as the Map parameter to maintain the order of the option vales.

Parameters:

options - the Map of option values and labels to add

Throws:

IllegalArgumentException - if options is null

addAll

public void addAll(String[] options)

Add the given array of string options to the Select option list.

The options array string value will be used for the Option.value and Option.label.

Parameters:

options - the array of option values to add

Throws:

IllegalArgumentException - if options is null

addAll

public void addAll(Collection objects,
                   String value,
                   String label)

Add the given collection of objects to the Select, creating new Option instances based on the object properties specified by value and label.

 Select select = new Select("type", "Type:");
 select.addAll(getCustomerService().getCustomerTypes(), "id", "name");
 form.add(select); 

Parameters:

objects - the collection of objects to render as options

value - the name of the object property to render as the Option value

label - the name of the object property to render as the Option label

Throws:

IllegalArgumentException - if options, value or label parameter is null

getSize

public int getSize()

Return the number of Select display rows.

Returns:

the number of Select display rows

setSize

public void setSize(int rows)

Set the number of the Select display rows.

Parameters:

rows - the Select display size in rows.

isMultiple

public boolean isMultiple()

Return true if multiple options can be selected.

Returns:

true if multiple options can be selected

setMultiple

public void setMultiple(boolean value)

Set the multiple options can be selected flag.

Parameters:

value - the multiple options can be selected flag

getMultipleValues

public List getMultipleValues()

Deprecated. use getSelectedValues() instead, this method will be removed in subsequent releases

Return the list of selected values.

Returns:

the list of selected values

getSelectedValues

public List getSelectedValues()

Return the list of selected values.

Returns:

the list of selected values

setMultipleValues

public void setMultipleValues(List multipleValues)

Deprecated. use getSelectedValues() instead, this method will be removed in subsequent releases

Set the list of selected values.

Parameters:

multipleValues - the list of selected values

setSelectedValues

public void setSelectedValues(List multipleValues)

Set the list of selected values.

Parameters:

multipleValues - the list of selected values

getOptionList

public List getOptionList()

Return the Option list.

Returns:

the Option list

setOptionList

public void setOptionList(List options)

Set the Option list.

Parameters:

options - the Option list

getValidationJavaScript

public String getValidationJavaScript()

Return the Select JavaScript client side validation function.

Overrides:

getValidationJavaScript in class Field

Returns:

the field JavaScript client side validation function

bindRequestValue

public void bindRequestValue()

Bind the request submission, setting the Field.value or selectedValues property if defined in the request.

Overrides:

bindRequestValue in class Field

getControlSizeEst

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

render

public void render(HtmlStringBuffer buffer)

Render the HTML representation of the Select.

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:

AbstractControl.toString()

validate

public void validate()

Validate the Select request submission.

If a Select is Field.required then the user must select a value other than the first value is the list, otherwise the Select will have a validation error. If the Select is not required then no validation errors will occur.

A field error message is displayed if a validation error occurs. These messages are defined in the resource bundle:

/click-control.properties

Error message bundle key names include:

• select-error

Overrides:

validate in class Field

setInitialValue

protected void setInitialValue()

Set the initial select option value.