net.sf.click.extras.control
Class CheckList

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

public class CheckList
extends Field

Provides a scrollable check list. This is an implementation of the Checklist from Check it don't select it

A scrollable check list is a more user friendly substitution for multiple-select-boxes. It is a scrollabe div which has many select-boxes.

To make the CheckList scrollable, set the height of the CheckList through setHeight(String).

Note when setting the height it is recommended that the CheckList should not be sortable, because of browser incompatibilities.

The CheckList is also sortable by drag-drop if the setSortable(boolean) property is set to true. In this case the method getSortorder() returns the keys of all the options whether they where selected or not in the order provided by the user.

Sortable is provided by scriptaculous which is only supported on IE6, FF and Safari1.2 and higher. This control is only tested on IE6 and FF on Windows. With IE the text of the dragged element has a black-outline which does not look good. To turn this off define an explicit back-ground color for the <li> elements. Typically you will do this in a style: .listClass li {background-color: #xxx}, where the listClass is set through AbstractControl.addStyleClass(String).

If a select is required at least one item must be selected so that the input is valid. Other validations are not done.

The Control listener will be invoked in any case whether the CheckList is valid or not.

The values of the CheckList are provided by Option instances. To populate the CheckList with Options, use the add methods.

The label of the Option is shown to the user and the value is what is provided in the getSelectedValues() and getSortorder() Lists.

The selected values can be retrieved from getSelectedValues(). The get/setValue() property is not supported.

The select uses the /click/checklist.css style. By providing a style which extends this style the appearance of the list can be changed.

To set the additional style class use AbstractControl.addStyleClass(String). This will append the given class to the default class of this control. Alternatively AbstractControl.setStyle(String, String) can be used to set the style of the outer div.

For an example please look at the click-examples and the at the above blog.

Author:
Christian Essl
See Also:
Option, Serialized Form

Field Summary
protected  String height
          The height if null not scrollable.
static String HTML_IMPORTS
          The HTML import statements.
static String JS_SORT_HTML_IMPORTS
          The JavaScript sorting HTML import statements.
protected  List optionList
          The Select Option list.
protected  List selectedValues
          The selected values.
protected  boolean sortable
          If sortable by drag and drop.
protected  List sortorder
          The key of the values in the order they are present (only set when sortable).
protected static String STYLE_CLASS
          The style class which is always set on this element (checkList).
protected static String VALIDATE_CHECKLIST_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
CheckList()
          Create a CheckList field with no name defined.
CheckList(String name)
          Create a CheckList field with the given name.
CheckList(String name, boolean required)
          Create a CheckList field with the given name and required status.
CheckList(String name, String label)
          Create a CheckList field with the given name and label.
CheckList(String name, String label, boolean required)
          Create a CheckList field with the given name, label and required status.
 
Method Summary
 void add(Option option)
          Add the given Option.
 void add(String value)
          Add the given option value.
 void addAll(Collection options)
          Add the given Option collection to the CheckList.
 void addAll(Collection objects, String value, String label)
          Add the given collection of objects to the CheckList, 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 CheckList.
 void addAll(String[] options)
          Add the given array of string options to the Select option list.
 void addStyle(String style)
          Deprecated. use @{link #setStyle(String, String)}
 void bindRequestValue()
          Bind the request submission, setting the selectedValues and sort order if the checkList is sortable.
 int getControlSizeEst()
           
 String getFocusJavaScript()
          Return the Field focus JavaScript.
 String getHeight()
          The css-height attribute.
 String getHtmlClass()
          Deprecated. use AbstractControl.getAttribute(String) instead
 String getHtmlImports()
          Returns the CSS and JavaScript imports and adds the script the checklist onload event.
 List getOptionList()
          Return the Option list.
 List getSelectedValues()
          Return the list of selected values.
 List getSortorder()
          A list of the values transmitted in the order they are present in the list.
 String getTag()
           
 String getValidationJavaScript()
          Return the CheckList JavaScript client side validation function.
 Object getValueObject()
          Returns the values list getValues() return a list or String.
 List getValues()
          Deprecated. use getSelectedValues() instead
 boolean isSortable()
          Whether the list is also sortable.
 void onDeploy(ServletContext servletContext)
          Deploys the style-sheet 'checklist.css' to the /click directory.
 void render(HtmlStringBuffer buffer)
          Render the HTML representation of the CheckList.
 void setHeight(String height)
          The css height attribute-value.
 void setHtmlClass(String clazz)
          Deprecated. use AbstractControl.addStyleClass(String) instead
 void setOptionList(List options)
          Set the Option list.
 void setSelectedValues(List selectedValues)
          Set the list of selected values.
 void setSortable(boolean sortable)
          Whether the list should be drag-drop sortable.
 void setValueObject(Object object)
          Set the value the value must be a List of String.
 void setValues(List values)
          Deprecated. use setSelectedValues(List) instead
protected  void sortOptions(String[] order)
          Sorts the current Options List.
 void validate()
          Validate the CheckList request submission.
 
Methods inherited from class net.sf.click.control.Field
getError, getErrorLabel, getFocus, getForm, getHelp, getId, getLabel, getRequestValue, getTabIndex, getTextAlign, getTitle, getValidate, getValue, 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, setWidth
 
Methods inherited from class net.sf.click.control.AbstractControl
addStyleClass, appendAttributes, getActionListener, getAttribute, getAttributes, getContext, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasStyles, 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

HTML_IMPORTS

public static final String HTML_IMPORTS
The HTML import statements.

See Also:
Constant Field Values

JS_SORT_HTML_IMPORTS

public static final String JS_SORT_HTML_IMPORTS
The JavaScript sorting HTML import statements.

See Also:
Constant Field Values

STYLE_CLASS

protected static final String STYLE_CLASS
The style class which is always set on this element (checkList).

See Also:
Constant Field Values

VALIDATE_CHECKLIST_FUNCTION

protected static final String VALIDATE_CHECKLIST_FUNCTION
The field validation JavaScript function template. The function template arguments are:

See Also:
Constant Field Values

height

protected String height
The height if null not scrollable.


optionList

protected List optionList
The Select Option list.


sortable

protected boolean sortable
If sortable by drag and drop.


sortorder

protected List sortorder
The key of the values in the order they are present (only set when sortable).


selectedValues

protected List selectedValues
The selected values.

Constructor Detail

CheckList

public CheckList(String name)
Create a CheckList field with the given name.

Parameters:
name - the name of the field

CheckList

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

Parameters:
name - the name of the field
label - the label of the field

CheckList

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

Parameters:
name - the name of the field
required - the field required status

CheckList

public CheckList(String name,
                 String label,
                 boolean required)
Create a CheckList 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

CheckList

public CheckList()
Create a CheckList field with no name defined.

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

Method Detail

getTag

public String getTag()
Returns:
this controls html tag
See Also:
AbstractControl.getTag()

add

public void add(Option option)
Add the given Option.

Parameters:
option - the Option value to add
Throws:
IllegalArgumentException - if option is null

add

public void add(String value)
Add the given option value. This convenience method will create a new Option with the given value and add it to the CheckList. 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 collection to the CheckList.

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 CheckList. 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 CheckList, creating new Option instances based on the object properties specified by value and label.
   CheckList list = new CheckList("type", "Type:");
   list.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

addStyle

public void addStyle(String style)
Deprecated. use @{link #setStyle(String, String)}

Adds the given style-value pair to the style attribute of the outer div. Does not check whether the style is already set.

Typically used for the width:

 list.addStyle(""width: 100%; height: 25em""); 

Parameters:
style - the style name:value pair without a ending ;

getFocusJavaScript

public String getFocusJavaScript()
Return the Field focus JavaScript.

Returns:
the Field focus JavaScript

setHeight

public void setHeight(String height)
The css height attribute-value. If null no height is set and the CheckList is not scrollable.

Parameters:
height - one of css height values (ie 40px) or null.

getHeight

public String getHeight()
The css-height attribute.

Returns:
Returns the height or null.

setHtmlClass

public void setHtmlClass(String clazz)
Deprecated. use AbstractControl.addStyleClass(String) instead

Set the given html class. The class will be set on the select list together with the STYLE_CLASS. Ie class="checkList my-class" where my-class is the set class. The default value is null.

Parameters:
clazz - the class to set or null

getHtmlClass

public String getHtmlClass()
Deprecated. use AbstractControl.getAttribute(String) instead

The html class to set on this control.

Returns:
the class or null (default null)
See Also:
setHtmlClass(String)

getHtmlImports

public String getHtmlImports()
Returns the CSS and JavaScript imports and adds the script the checklist onload event.

Returns:
the two import tags
See Also:
AbstractControl.getHtmlImports()

getOptionList

public List getOptionList()
Return the Option list.

Returns:
a list of Option objects

setOptionList

public void setOptionList(List options)
Set the Option list. Note: if the CheckList is sortable than the List must be fully modifiable, because it will be sorted according to the order chosen by the user.

Parameters:
options - a list of Option objects

setSortable

public void setSortable(boolean sortable)
Whether the list should be drag-drop sortable. This is supported by scriptaculous. Note when the list also has a size than this might not work on different browsers.

Parameters:
sortable - default is false.

isSortable

public boolean isSortable()
Whether the list is also sortable.

Returns:
Returns the sortable.

getSortorder

public List getSortorder()
A list of the values transmitted in the order they are present in the list. This is only available if the list is sortable

Returns:
Returns list of strings of the option values.

getValues

public List getValues()
Deprecated. use getSelectedValues() instead

Return the list of selected values. The values are the values of the Options selected.

Returns:
a list of Strings

getSelectedValues

public List getSelectedValues()
Return the list of selected values. The values are the values of the Options selected.

Returns:
the list of selected values

setValues

public void setValues(List values)
Deprecated. use setSelectedValues(List) instead

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

Parameters:
values - a list of strings or null

setSelectedValues

public void setSelectedValues(List selectedValues)
Set the list of selected values. The specified values must match the values of the Options.

For example:

 CheckList checkList = new CheckList("checkList");

 public void onInit() {
     List options = new ArrayList();
     options.add(new Option("1", "Option 1");
     options.add(new Option("2", "Option 2");
     options.add(new Option("3", "Option 3");
     checkList.setOptionList(options);
 }

 public void onRender() {
     // Preselect some Options.
     List selected = new ArrayList();
     selected.add("1"));
     selected.add("3");
     checkList.setSelectedValues(selected);
 } 

Parameters:
selectedValues - the list of selected string values or null

getValueObject

public Object getValueObject()
Returns the values list getValues() return a list or String.

Returns:
List of selected values (Strings)
See Also:
Field.getValueObject()

setValueObject

public void setValueObject(Object object)
Set the value the value must be a List of String.

Parameters:
object - a List or null
See Also:
Field.setValueObject(java.lang.Object)

getValidationJavaScript

public String getValidationJavaScript()
Return the CheckList JavaScript client side validation function.

Returns:
the field JavaScript client side validation function

bindRequestValue

public void bindRequestValue()
Bind the request submission, setting the selectedValues and sort order if the checkList is sortable.


sortOptions

protected void sortOptions(String[] order)
Sorts the current Options List. This method is called in bindRequestValue() when the CheckList is sortable.

Parameters:
order - values in the order to sort the list.

onDeploy

public void onDeploy(ServletContext servletContext)
Deploys the style-sheet 'checklist.css' to the /click directory.

Parameters:
servletContext - the context
See Also:
AbstractControl.onDeploy(javax.servlet.ServletContext)

getControlSizeEst

public int getControlSizeEst()
Returns:
the estimated rendered control size in characters
See Also:
AbstractControl.getControlSizeEst()

render

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

Parameters:
buffer - the specified buffer to render the control's output to
See Also:
AbstractControl.toString()

validate

public void validate()
Validate the CheckList request submission.

If a CheckList is Field.required then the user must select a value, 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: