org.apache.click.extras.control
Class CheckList

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

All Implemented Interfaces:

Serializable, Control, Stateful

public class CheckList
extends Field

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

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

CheckList Examples

 public class MyPage extends Page {

     public void onInit() {

         CheckList checkList = new ChecList("languages");

         checkList.add(new Option("001", "Java"));
         checkList.add(new Option("002", "Ruby"));
         checkList.add(new Option("003", "Perl"));

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

Unless you use a DataProvider, remember to always populate the CheckList 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 CheckList optionList in. To alleviate this problem you can set a dataProvider which allows the CheckList to fetch data when needed. This is particularly useful if retrieving CheckList 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 languageCheckList = new CheckList("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
         languageCheckList.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(languageCheckList);

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

CheckList also supports a scrollable mode. 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/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.

CSS and JavaScript resources

The CheckList control makes use of the following resources (which Click automatically deploys to the application directories, /click/checklist and /click/prototype):

• click/checklist/checklist.css
• click/checklist/checklist.js
• click/prototype/builder.js
• click/prototype/controls.js
• click/prototype/dragdrop.js
• click/prototype/effects.js
• click/prototype/prototype.js
• click/prototype/slider.js

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

See Also:

Option, Serialized Form

Field Summary

protected DataProvider<Option>	dataProvider The select data provider.
protected String	height The height if null not scrollable.
protected List<Option>	optionList The Select Option list.
protected List<String>	selectedValues The selected values.
protected boolean	sortable If sortable by drag and drop.
protected List<String>	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 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

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(Object option) Add the given Option/String/Number/Boolean to the CheckList.
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/String/Number/Boolean collection to the CheckList.
void	addAll(Collection<?> objects, String optionValueProperty, String optionLabelProperty) Add the given collection of objects to the CheckList, 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 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()
DataProvider<Option>	getDataProvider() Return the CheckList optionList DataProvider.
String	getFocusJavaScript() Return the Field focus JavaScript.
List<Element>	getHeadElements() Return the CheckList HEAD elements to be included in the page.
String	getHeight() The css-height attribute.
String	getHtmlClass() Deprecated. use AbstractControl.getAttribute(String) instead
List<Option>	getOptionList() Return the Option list.
List<String>	getSelectedValues() Return the list of selected values as a List of Strings.
List<String>	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() This method delegates to getSelectedValues() to return the selected values as a java.util.List of Strings.
List<String>	getValues() Deprecated. use getSelectedValues() instead
boolean	isSortable() Whether the list is also sortable.
boolean	onProcess() Process the request Context setting the CheckList selectedValues if selected and invoking the control's listener if defined.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the CheckList.
void	setDataProvider(DataProvider<Option> dataProvider) Set the CheckList option list DataProvider.
void	setHeight(String height) The css height attribute-value.
void	setHtmlClass(String clazz) Deprecated. use AbstractControl.addStyleClass(String) instead
void	setOptionList(List<Option> options) Set the Option list.
void	setSelectedValues(List<String> selectedValues) Set the list of selected values.
void	setSortable(boolean sortable) Whether the list should be drag-drop sortable.
void	setValueObject(Object object) This method delegates to setSelectedValues(java.util.List) to set the selected values of the CheckList.
void	setValues(List<String> 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 org.apache.click.control.Field

getError, getErrorLabel, getFocus, getForm, getHelp, getId, getLabel, getLabelStyle, getLabelStyleClass, getParentStyleClassHint, getParentStyleHint, getRequestValue, getState, getTabIndex, getTextAlign, getTitle, getValidate, getValue, getWidth, isDisabled, isHidden, isReadonly, isRequired, isTrim, isValid, removeState, renderTagBegin, restoreState, saveState, setDisabled, setError, setErrorMessage, setErrorMessage, setFocus, setForm, setHelp, setLabel, setLabelStyle, setLabelStyleClass, setListener, setParent, setParentStyleClassHint, setParentStyleHint, setReadonly, setRequired, setState, 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, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, onDestroy, onInit, onRender, removeBehavior, removeStyleClass, 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

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 name of the checkbox
• 2 - is the id of the form
• 3 - is the Field required status
• 4 - is the localized error message for required validation

See Also:

Constant Field Values

dataProvider

protected DataProvider<Option> dataProvider

The select data provider.

height

protected String height

The height if null not scrollable.

optionList

protected List<Option> optionList

The Select Option list.

sortable

protected boolean sortable

If sortable by drag and drop.

sortorder

protected List<String> sortorder

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

selectedValues

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

Overrides:

getTag in class AbstractControl

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

add

public void add(Object option)

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

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 CheckList.

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 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 optionValueProperty,
                   String optionLabelProperty)

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

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

For example given the 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 CheckList optionList DataProvider.

Returns:

the CheckList optionList DataProvider

setDataProvider

public void setDataProvider(DataProvider<Option> dataProvider)

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

Example usage:

 CheckList checkList = new CheckList("languages");

 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 CheckList option list DataProvider

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.

Overrides:

getFocusJavaScript in class Field

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)

getHeadElements

public List<Element> getHeadElements()

Return the CheckList HEAD elements to be included in the page. The following resources are returned:

• click/checklist/checklist.css
• click/checklist/checklist.js
• click/prototype/builder.js
• click/prototype/controls.js
• click/prototype/dragdrop.js
• click/prototype/effects.js
• click/prototype/prototype.js
• click/prototype/slider.js

Specified by:

getHeadElements in interface Control

Overrides:

getHeadElements in class AbstractControl

Returns:

the HTML head import statements for the control

See Also:

Control.getHeadElements()

getOptionList

public List<Option> getOptionList()

Return the Option list.

Returns:

the Option list

setOptionList

public void setOptionList(List<Option> 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<String> 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<String> getValues()

Deprecated. use getSelectedValues() instead

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

Returns:

a list of Strings

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:

the list of selected values

setValues

public void setValues(List<String> values)

Deprecated. use setSelectedValues(List) instead

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

Parameters:

values - a list of strings or null

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:

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

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 CheckList. 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)

getValidationJavaScript

public String getValidationJavaScript()

Return the CheckList JavaScript client side validation function.

Overrides:

getValidationJavaScript in class Field

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.

Overrides:

bindRequestValue in class Field

onProcess

public boolean onProcess()

Process the request Context setting the CheckList selectedValues if selected and invoking the control's listener if defined.

Specified by:

onProcess in interface Control

Overrides:

onProcess in class Field

Returns:

true to continue Page event processing, false otherwise

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.

getControlSizeEst

public int getControlSizeEst()

Overrides:

getControlSizeEst in class AbstractControl

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.

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:

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:

validate in class Field