org.apache.click.extras.control
Class PickList

java.lang.Object
  org.apache.click.control.AbstractControl
      org.apache.click.control.Field
          org.apache.click.extras.control.PickList

All Implemented Interfaces:

Serializable, Control, Stateful

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 similar to a Select field.

PickList Examples

The following code shows how the previous example was rendered:

 public class MyPage extends Page {

     public void onInit() {

         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"));

         // Set the Java as a selected option
         pickList.addSelectedValue("001");
     }
 } 

Unless you use a DataProvider, remember to always populate the PickList option list before it is processed. Do not populate the option list in a Page's onRender() method.

DataProvider

A common issue new Click users face is which page event (onInit or onRender) to populate the PickList optionList in. To alleviate this problem you can set a dataProvider which allows the PickList to fetch data when needed. This is particularly useful if retrieving PickList data is expensive e.g. loading from a database.

Below is a simple example:

 public class LanguagePage extends Page {

     public Form form = new Form();

     private Select languagePickList = new PickList("languages");

     public LanguagePage() {

         // Set a DataProvider which "getData" method will be called to
         // populate the optionList. The "getData" method is only called when
         // the optionList data is needed
         languagePickList.setDataProvider(new DataProvider() {
             public List getData() {
                 List options = new ArrayList();
                 options.add(new Option("001", "Java"));
                 options.add(new Option("002", "Ruby"));
                 options.add(new Option("003", "Perl"));
                 return options;
             }
         });

         form.add(languagePickList);

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

Retrieving selected values

The selected values can be retrieved from getSelectedValues().

 public void onInit() {
     ...
     form.add(pickList);

     // Add a submit button with a listener
     form.add(new Submit("OK", this, "onSubmitClick"));
 }

 public boolean onSubmitClick() {
     if (form.isValid()) {
         Set selectedValues = languagePickList.getSelectedValues();
         for (Object languageValue : selectedValues) {
             ...
         }
     }
 } 

CSS and JavaScript resources

The PickList control makes use of the following resources (which Click automatically deploys to the application directory, /click):

• click/extras-control.js

To import these CheckList files simply reference the variables $headElements and $jsElements in the page template.

See Also:

Serialized Form

Field Summary

protected DataProvider<Option>	dataProvider The select data provider.
protected int	height The list height.
protected List<Option>	optionList The Option list.
protected String	selectedLabel The label text for the selected list.
protected List<String>	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 org.apache.click.control.Field

disabled, error, focus, form, help, label, labelStyle, labelStyleClass, parentStyleClassHint, parentStyleHint, readonly, required, tabindex, title, trim, validate, value

Fields inherited from class org.apache.click.control.AbstractControl

actionListener, attributes, behaviors, headElements, listener, listenerMethod, messages, name, parent, styles

Fields inherited from interface org.apache.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(Object option) Add the given Option/String/Number/Boolean to the PickList.
void	add(Option option) Add the given Option to the PickList.
void	addAll(Collection<?> options) Add the given Option/String/Number/Boolean collection to the PickList.
void	addAll(Collection<?> objects, String optionValueProperty, String optionLabelProperty) Add the given collection of objects to the PickList, creating new Option instances based on the object properties specified by optionValueProperty and optionLabelProperty.
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 to the List of selectedValues.
void	bindRequestValue() Bind the request submission, setting the selectedValues property if defined in the request.
DataProvider<Option>	getDataProvider() Return the PickList optionList DataProvider.
List<Element>	getHeadElements() Returns the PickList HTML HEAD elements for the click/extras-control.js resource.
int	getHeight() Return the list height.
List<Option>	getOptionList() Return the Option list.
List<String>	getSelectedValues() Return the list of selected values as a List of Strings.
int	getSize() Return the component size (width) in pixels.
Object	getState() Return the PickList state.
String	getValidationJavaScript() Return the field JavaScript client side validation function.
Object	getValueObject() This method delegates to getSelectedValues() to return the selected values as a java.util.List of Strings.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the PickList.
protected void	renderTemplate(HtmlStringBuffer buffer, Map<String,Object> model) Render a Velocity template for the given data model.
void	setDataProvider(DataProvider dataProvider) Set the PickList option list DataProvider.
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	setOptionList(List<Option> options) Set the Option list.
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	setSelectedValues(List<String> selectedValues) Set the list of selected values.
void	setSize(int size) Set the component size.
void	setState(Object state) Set the PickList state.
void	setValueObject(Object object) This method delegates to setSelectedValues(java.util.List) to set the selected values of the PickList.
String	toString() Return a HTML rendered PickList string.
void	validate() Validate the PickList request submission.

Methods inherited from class org.apache.click.control.Field

getError, getErrorLabel, getFocus, getFocusJavaScript, getForm, getHelp, getId, getLabel, getLabelStyle, getLabelStyleClass, getParentStyleClassHint, getParentStyleHint, getRequestValue, getTabIndex, getTextAlign, getTitle, getValidate, getValue, getWidth, isDisabled, isHidden, isReadonly, isRequired, isTrim, isValid, onProcess, removeState, renderTagBegin, restoreState, saveState, setDisabled, setError, setErrorMessage, setErrorMessage, setFocus, setForm, setHelp, setLabel, setLabelStyle, setLabelStyleClass, setListener, setParent, setParentStyleClassHint, setParentStyleHint, setReadonly, setRequired, setTabIndex, setTextAlign, setTitle, setTrim, setValidate, setValue, setWidth

Methods inherited from class org.apache.click.control.AbstractControl

addBehavior, addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getControlSizeEst, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, getTag, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, onDestroy, onInit, onRender, removeBehavior, removeStyleClass, renderTagEnd, setActionListener, setAttribute, setId, setName, setStyle

Methods inherited from class java.lang.Object

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

Field Detail

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

dataProvider

protected DataProvider<Option> dataProvider

The select data provider.

height

protected int height

The list height. The default height is 8.

optionList

protected List<Option> optionList

The Option list.

selectedLabel

protected String selectedLabel

The label text for the selected list.

selectedValues

protected List<String> 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

add

public void add(Object option)

Add the given Option/String/Number/Boolean to the PickList.

Parameters:

option - one of either Option/String/Number/Boolean to add

Throws:

IllegalArgumentException - if option is null, or the option is an unsupported class

addAll

public void addAll(Collection<?> options)

Add the given Option/String/Number/Boolean collection to the PickList.

Parameters:

options - the collection of Option/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 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 optionValueProperty,
                   String optionLabelProperty)

Add the given collection of objects to the PickList, creating new Option instances based on the object properties specified by optionValueProperty and optionLabelProperty.

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

For example, given a Collection of CustomerType objects, optionValueProperty "id" and optionLabelProperty "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 id and name retrieved from the CustomerType instance.

Parameters:

objects - the collection of objects to render as options

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

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

Throws:

IllegalArgumentException - if objects or optionValueProperty parameter is null

getDataProvider

public DataProvider<Option> getDataProvider()

Return the PickList optionList DataProvider.

Returns:

the PickList optionList DataProvider

setDataProvider

public void setDataProvider(DataProvider dataProvider)

Set the PickList option list DataProvider. The dataProvider must return a list containing Option values.

Example usage:

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

 select.setDataProvider(new DataProvider() {
     public List getData() {
         List options = new ArrayList();
         options.add(new Option("001", "Java"));
         options.add(new Option("002", "Ruby"));
         options.add(new Option("003", "Perl"));
         return options;
     }
 }); 

Parameters:

dataProvider - the PickList option list DataProvider

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<Option> getOptionList()

Return the Option list.

Returns:

the Option list

setOptionList

public void setOptionList(List<Option> options)

Set the Option list.

Parameters:

options - 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

getHeadElements

public List<Element> getHeadElements()

Returns the PickList HTML HEAD elements for the click/extras-control.js resource.

Specified by:

getHeadElements in interface Control

Overrides:

getHeadElements in class AbstractControl

Returns:

the HTML HEAD elements for the control

See Also:

Control.getHeadElements()

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 to the List of selectedValues.

Parameters:

value - the selected value to add

Throws:

IllegalArgumentException - if the value is null

getSelectedValues

public List<String> getSelectedValues()

Return the list of selected values as a List of Strings. The returned List will contain the values of the Options selected.

Returns:

selected values as a List of Strings

setSelectedValues

public void setSelectedValues(List<String> selectedValues)

Set the list of selected values. The specified values must be Strings and match the values of the Options.

For example:

 PickList pickList = new PickList("languages");

 public void onInit() {
     pickList.add(new Option("005", "Java"));
     pickList.add(new Option("006", "Ruby"));
     pickList.add(new Option("007", "Perl"));
     ...
 }

 public void onRender() {
     // Preselect Java and Perl.
     List selected = new ArrayList();
     selected.add("005");
     selected.add("007");
     pickList.setSelectedValues(selected);
 } 

Parameters:

selectedValues - the list of selected string values or null

getValueObject

public Object getValueObject()

This method delegates to getSelectedValues() to return the selected values as a java.util.List of Strings.

Overrides:

getValueObject in class Field

Returns:

selected values as a List of Strings

See Also:

Field.getValueObject(), getSelectedValues()

setValueObject

public void setValueObject(Object object)

This method delegates to setSelectedValues(java.util.List) to set the selected values of the PickList. The given object parameter must be a java.util.List of Strings, otherwise it is ignored.

The List of values match the values of the Options.

Overrides:

setValueObject in class Field

Parameters:

object - a List of Strings

See Also:

Field.setValueObject(java.lang.Object), setSelectedValues(java.util.List)

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

getState

public Object getState()

Return the PickList state. The following state is returned:

• getSelectedValues()

Specified by:

getState in interface Stateful

Overrides:

getState in class Field

Returns:

the PickList state

setState

public void setState(Object state)

Set the PickList state.

Specified by:

setState in interface Stateful

Overrides:

setState in class Field

Parameters:

state - the PickList state to set

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:

org.apache.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<String,Object> 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