net.sf.click.extras.control
Class CheckList

java.lang.Object
  net.sf.click.control.AbstractControl
      net.sf.click.control.Field
          net.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:

• 0 - is the field id
• 1 - is the full path name to the checkbox
• 2 - is the Field required status
• 3 - is the localized error message for required validation

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: