org.apache.click.extras.control
Class PickList

java.lang.Object
  extended by org.apache.click.control.AbstractControl
      extended by org.apache.click.control.Field
          extended by 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



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): 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:

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:

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