net.sf.click.extras.control
Class PickList

java.lang.Object
  extended bynet.sf.click.control.AbstractControl
      extended bynet.sf.click.control.Field
          extended bynet.sf.click.extras.control.PickList
All Implemented Interfaces:
Control, Serializable

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 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, 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, getControlSizeEst, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, getTag, hasAttribute, hasAttributes, hasStyles, onDestroy, onRender, registerActionEvent, removeStyleClass, renderTagBegin, 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

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:

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.

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.

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.


onDeploy

public void onDeploy(ServletContext servletContext)
Deploy the extras-control.js file to the click web directory when the application is initialized.

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


render

public void render(HtmlStringBuffer buffer)
Render the HTML representation of the PickList.

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.

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