net.sf.click.extras.control
Class PickList

java.lang.Object
  net.sf.click.control.AbstractControl
      net.sf.click.control.Field
          net.sf.click.extras.control.PickList

All Implemented Interfaces:

Serializable, Control

public class PickList
extends Field

Provides a twin multiple Select box control to select items.

Languages		Selected
Ruby Perl		Java

The values of the PickList are provided by Option objects like for a Select.

PickList Examples

The following code shows the previous rendering example:

 PickList pickList = new PickList("languages");
 pickList.setHeaderLabel("Languages", "Selected");

 pickList.add(new Option("001", "Java"));
 pickList.add(new Option("002", "Ruby"));
 pickList.add(new Option("003", "Perl"));

 pickList.addSelectedValue("001"); 

The selected values can be retrieved from getSelectedValues().

 Set selectedValues = pickList.getSelectedValues();

 for (Iterator i = selectedValues.iterator(); i.hasNext();){
     String value = (String) i.next();
     ...
 } 

Author:

Naoki Takezoe

See Also:

Serialized Form

Field Summary

protected int	height The list height.
static String	HTML_IMPORTS The Palette.js imports statement.
protected List	optionList The Option list.
protected String	selectedLabel The label text for the selected list.
protected List	selectedValues The selected values.
protected int	size The component size (width) in pixels.
protected String	unselectedLabel The label text for the unselected list.
protected static String	VALIDATE_PICKLIST_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

PickList()
Create a PickList with no name defined.

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

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

Method Summary

void	add(Option option) Add the given Option to the PickList.
void	addAll(Collection options) Add the given Option collection to the PickList.
void	addAll(Collection objects, String value, String label) Add the given collection of objects to the PickList, 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 PickList.
void	addAll(String[] options) Add the given array of string options to the PickList.
void	addSelectedValue(String value) Add the selected value.
void	bindRequestValue() Bind the request submission, setting the selectedValues property if defined in the request.
int	getHeight() Return the list height.
String	getHtmlImports() Return the HTML head import statements for the JavaScript (click/extras-control.js) file.
List	getOptionList() Return the Option list.
List	getSelectedValues() Return selected values.
int	getSize() Return the component size (width) in pixels.
String	getValidationJavaScript() Return the field JavaScript client side validation function.
void	onDeploy(ServletContext servletContext) Deploy the extras-control.js file to the click web directory when the application is initialized.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the PickList.
protected void	renderTemplate(HtmlStringBuffer buffer, Map model) Render a Velocity template for the given data model.
void	setHeaderLabel(String unselectedLabel, String selectedLabel) Set the header label text for the selected list and the unselected list.
void	setHeight(int height) Set the list height.
void	setSelectedValues(Collection objects, String value) The PickList selected values will be derived from the given collection of objects, based on the object properties specified by value.
void	setSize(int size) Set the component size.
String	toString() Return a HTML rendered PickList string.
void	validate() Validate the PickList 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, setReadonly, setRequired, setTabIndex, setTextAlign, setTitle, setValidate, setValue, setValueObject, setWidth

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

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

Methods inherited from class java.lang.Object

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

Field Detail

HTML_IMPORTS

public static final String HTML_IMPORTS

The Palette.js imports statement.

See Also:

Constant Field Values

VALIDATE_PICKLIST_FUNCTION

protected static final String VALIDATE_PICKLIST_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 for required validation

See Also:

Constant Field Values

height

protected int height

The list height. The default height is 8.

optionList

protected List optionList

The Option list.

selectedLabel

protected String selectedLabel

The label text for the selected list.

selectedValues

protected List selectedValues

The selected values.

size

protected int size

The component size (width) in pixels. The default size is 400px.

unselectedLabel

protected String unselectedLabel

The label text for the unselected list.

Constructor Detail

PickList

public PickList(String name,
                String label)

Create a PickList field with the given name and label.

Parameters:

name - the name of the field

label - the label of the field

PickList

public PickList(String name)

Create a PickList field with the given name.

Parameters:

name - the name of the field

PickList

public PickList()

Create a PickList with no name defined.

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

Method Detail

add

public void add(Option option)

Add the given Option to the PickList.

Parameters:

option - the Option value to add

Throws:

IllegalArgumentException - if option is null

addAll

public void addAll(Collection options)

Add the given Option collection to the PickList.

Parameters:

options - the collection of Option objects to add

Throws:

IllegalArgumentException - if options is null

addAll

public void addAll(Map options)

Add the given Map of option values and labels to the PickList. 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 PickList.

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 PickList, creating new Option instances based on the object properties specified by value and label.

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

For example given the Collection of CustomerType objects, value "id" and label "name", the id and name properties of each CustomerType will be retrieved. For each CustomerType in the Collection a new Option instance is created and its value and label is set to the value and label retrieved from the CustomerType instance.

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

setHeaderLabel

public void setHeaderLabel(String unselectedLabel,
                           String selectedLabel)

Set the header label text for the selected list and the unselected list. The specified text is displayed at the top of the list.

Parameters:

unselectedLabel - the label text for the unselected list

selectedLabel - the label text for the selected list

getOptionList

public List getOptionList()

Return the Option list.

Returns:

the Option list

getHeight

public int getHeight()

Return the list height.

Returns:

the list height

setHeight

public void setHeight(int height)

Set the list height.

Parameters:

height - the list height

getHtmlImports

public String getHtmlImports()

Return the HTML head import statements for the JavaScript (click/extras-control.js) file.

Specified by:

getHtmlImports in interface Control

Overrides:

getHtmlImports in class AbstractControl

Returns:

the HTML head import statements for the JavaScript file

See Also:

Control.getHtmlImports()

setSelectedValues

public void setSelectedValues(Collection objects,
                              String value)

The PickList selected values will be derived from the given collection of objects, based on the object properties specified by value.

Example usage:

   PickList list = new PickList("type", "Type:");

   // Fill the PickList with product types
   list.addAll(getCustomerService().getProductTypes(), "id", "name");

   // Set the PickList selected values to the list of products of the
   // current customer
   list.setSelectedValues(getCustomer().getProductTypes(), "id");
   form.add(list); 

For example given the Collection of ProductType objects and the value "id", the id property of each ProductType will be retrieved and added to the PickList selectedValues.

Parameters:

objects - the collection of objects to render selected values

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

Throws:

IllegalArgumentException - if options or value parameter is null

addSelectedValue

public void addSelectedValue(String value)

Add the selected value.

Parameters:

value - the selected value

Throws:

IllegalArgumentException - if the value is null

getSelectedValues

public List getSelectedValues()

Return selected values.

Returns:

selected values

setSize

public void setSize(int size)

Set the component size.

Parameters:

size - the component size

getSize

public int getSize()

Return the component size (width) in pixels.

Returns:

the component size

getValidationJavaScript

public String getValidationJavaScript()

Return the field JavaScript client side validation function.

The function name must follow the format validate_[id], where the id is the DOM element id of the fields focusable HTML element, to ensure the function has a unique name.

Overrides:

getValidationJavaScript in class Field

Returns:

the field JavaScript client side validation function

bindRequestValue

public void bindRequestValue()

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

Overrides:

bindRequestValue in class Field

onDeploy

public void onDeploy(ServletContext servletContext)

Deploy the extras-control.js file to the click web directory when the application is initialized.

Specified by:

onDeploy in interface Control

Overrides:

onDeploy in class AbstractControl

Parameters:

servletContext - the servlet context

See Also:

Control.onDeploy(ServletContext)

validate

public void validate()

Validate the PickList request submission.

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

net.sf.click.control.MessageProperties

Error message bundle key names include:

• field-required-error

Overrides:

validate in class Field

render

public void render(HtmlStringBuffer buffer)

Render the HTML representation of the PickList.

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:

toString()

toString

public String toString()

Return a HTML rendered PickList string.

Overrides:

toString in class AbstractControl

Returns:

a HTML rendered PickList string

renderTemplate

protected void renderTemplate(HtmlStringBuffer buffer,
                              Map model)

Render a Velocity template for the given data model.

Parameters:

buffer - the specified buffer to render the template output to

model - the model data to merge with the template