Control.SelectMultiple
Unobtrusive select multiple input alternative for Prototype.js
Introduction
This control uses a combination of a standard select input, and a collection of checkbox inputs to create an alternative to the standard select multiple control. It's primary benefit besides a vastly improved experience for selecting multiple items is that for single item selection, it behaves like a normal select input.
As demonstrated below, selecting an item in the select input will check the appropriate box, and checking one of the checkboxes will select the appropriate option in the select. If multiple boxes are checked a new option is dynamically added to the select. All aspects of this behavior can be programatically controlled.
Examples
Below is a simple, unstyled example. Check one or more boxes, then change the select input to see how it behaves.
One Two Three Value in Form:The next example is more in line with it's intended use case. Note that the effects are not part of this library, but are easily accomplished with Scriptaculous. Try selecting many values to see the overflow behavior described in the API section.
Sample Code
<select id="select_multiple">
<option value="1">One</option>
<option value="2">Two</option>
<option value="3">Three</option>
</select>
<span id="select_multiple_options">
<input type="checkbox" value="1"/><span class="name">One</span>
<input type="checkbox" value="2"/><span class="name">Two</span>
<input type="checkbox" value="3"/><span class="name">Three</span>
</span>
<script>
new Control.SelectMultiple('select_multiple','select_multiple_options');
</script>How to Read the API Table
Anything in the method and property lists that ends with "()" is a method, and anything that doesn't is a property. All events are specifiable in the options hash, or via "observe()" if Object.Event has been included on the page before Control.SelectMultiple was. In a method signature, each argument is separated by a comma, if the words are lower case it refers to the data type and gives a hint to what it is used for, if there is an upper case word it refers to the class of object that must be used. Arguments with [square brackets] around them are optional.
Methods and Properties
| Return | Name | Description |
| Control.SelectMultiple | initialize(mixed select_id, mixed container_id [,options Hash]) | Pass in string ids, or Element objects to the select input, and a container with checkboxes |
| void | setValue(mixed value) | value string should be a string of values separated by the valueSeparator, or an array of values. |
| Element | select | |
| Element | container | |
| int | numberOfCheckedBoxes | |
| array | checkboxes | |
| false | hasExtraOption |
Options
| Type | Name | Default | Description |
| string | checkboxSelector | 'input[type=checkbox]' | CSS selector applied to the container to get the list of checkboxes |
| string | nameSelector | 'span.name' | CSS selector applied to the container to get the list of labels |
| string | labelSeparator | ', ' | |
| string | valueSeparator | ',' | |
| function | afterChange | function(value){} | |
| mixed | overflowString | function(str){return str.truncate();} | string, or a function that returns a string if the label is to long for the input |
| int | overflowLength | 30 | Number of characters in the label before it is replaced with overflowString |
Events
All events can be passed in as an option, or if Object.Event has been included, they can be observed by calling Control.Tabs.observe() to observe all instances, or by calling observe() on any particular instance to just observe that one.
| Name | Description |
| afterChange(string new_value) | Called whenever the value of the select changes. This is more inclusive than the 'change' event of the select Element, because it includes when a checkbox is clicked, or when setValue() is called. |
RSS Changelog
Is available at http://livepipe.net/projects/control_select_multiple/changelog.rss
Downloads & SVN
The Control Suite subversion repository is available at: svn://livepipe.net/control_suite/
Other Resources
Have you written a post or article about Control.SelectMultiple? Please contact me!