jQuery MultiSelect Plugin w/ ThemeRoller Support ~ vZhai: Info Sharing Blog

jQuery MultiSelect Plugin w/ ThemeRoller Support

jQuery MultiSelect Plugin w/ ThemeRoller Support: "

Update 05/04/2010: Version 0.6 is out! Download below, and read the changelog.

I’ve been working on a multiple select plugin on and off for the past couple months and finally have it stable enough for a first release. When I started this project my intentions were only to re-factor Cory LaViska’s MultiSelect implementation, but it quickly turned into a complete re-write with a focus on speed and ThemeRoller support. This plugin turns an ordinary HTML select control into an elegant drop down list of checkboxes. jQuery MultiSelect

Current version: 0.6 (05/04/2010 – Changelog)
View demos
Download source (12.5 kb) or minified (6.8 kb), and the CSS file.
Follow this project on GitHub

Features

Full ThemeRoller support.
Optgroup support with clickable labels.
Optional header with check all / uncheck all / close links.
Degrades gracefully.
Keyboard support.
Ability to hook into 5 different event callbacks.
Display the checked options in a list with a configurable maximum.
Easily change the position, fade speed, scroll container height, links text, and input text.
The widget width inherits from the original element, but is also configurable as a parameter.
Pre-selected & disabled option/widget support.
bgiframe support.
Only 6.9kb minified (2kb Gzipped).

Compatibility

MultiSelect is compatible with jQuery 1.4.0+ and all themes from jQuery UI 1.7+. This plugin is known to work in (but not limited to):

Firefox 2 – 3.6
IE 6 – 8
Chrome Beta/4
Safari 4
Opera 10

Usage

First ensure you’ve included jQuery 1.4, a jQuery UI theme of your choice, and the jquery.multiselect.css file. You don’t need the jQuery UI library itself, just the theme files. The simplest use of MultiSelect is to bind the widget to your select box:

<select id="MySelectBox" multiple="multiple" name="MySelectBox">
<option value="1">Option 1</option>
<option value="2">Option 2</option>
</select>

$(document).ready(function(){
   $("#MySelectBox").multiSelect();
});

Do not forget to set your select boxes to multiple='multiple' if you want this plugin to degrade gracefully. Any option tags with the selected='selected' attribute will automatically be checked by default, and any option tags with the disabled='disabled' attribute will automatically be disabled by default.

Callbacks

Inside the onOpen callback, this refers to the container holding the header and checkboxes. If you want to gather all the checkboxes inside the multiselect that just opened, for example:

$("#MySelectBox").multiSelect({
 onOpen: function(){
  var $checkboxes = $(this).find('input');
 }
});

Inside the onClick callback, this refers to the checkbox that received the event. Example:

$("#MySelectBox").multiSelect({
 onClick: function(){
  if(this.checked){
   alert("I was just checked!");
  }
 }
});

See the options below for a full list of callbacks.

Overriding Options

Options for this plugin are exposed in $.fn.multiSelect.defaults, so you can override the default options for all instances like such:

// set the minWidth parameter for all instances to 500 pixels
$.fn.multiSelect.defaults.minWidth = 500;

Passing a function to the selectedText parameter

As of 0.5, the selectedText parameter can accept an anonymous function with three arguments: the number of checkboxes checked, the total number of checkboxes, and an array of the checked checkbox DOM elements. As you can see in the example, this gives you 100% control of the display:

$("#MySelectBox").multiSelect({
 selectedText: function(numChecked, numTotal, checkedInputs){

  // example: emulating the default behavior
  return numChecked + " checked";

  // example: emulating the selectedList option
  return (numChecked < = 5)
   ? checkedInputs.map(function(element){ return element.title; }).join(', ')
   : numChecked + " checked";
 }
});

Options

This plugin is configurable with the following options:

Parameter	Description	Default
showHeader	A boolean value denoting whether or not to display the header containing the check all, uncheck all, and close links.	true
maxHeight	The maximum height in pixels of the scrolling container that holds the checkboxes.	175
minWidth	The minimum width in pixels of widget. Setting to `auto` (default) will inherit the width from the original select element.	200
checkAllText	The default text of the “Check all” link.	Check all
unCheckAllText	The default text of the “Uncheck all” link.	Uncheck all
noneSelectedText	Renamed from `noneSelected` in 0.5! The default text the select box when no options have been selected.	Select options
selectedList	A boolean/numeric value denoting whether or not to display the checked opens in a list, and how many. A number greater than 0 denotes the maximum number of list items to display before switching over to the `selectedText` parameter. A value of 0 or `false` is disabled.	false
selectedText	The text to display in the select box when options are selected (if selectedList is false). The pound sign (#) is automatically replaced by the number of checkboxes selected. If two pound signs are present in this parameter, the second will be replaced by the total number of checkboxes available. Example: “# of # checked”. New in 0.5! As of 0.5, this parameter can also accept an anonymous function with three arguments: the number of checkboxes checked, the total number of checkboxes, and an array of the checked checkbox DOM elements. See the examples.	# selected
position	The position of the options menu relative to the input control: top, middle, or bottom.	bottom
shadow	A boolean value denoting whether to apply a CSS shadow (class ui-multiselect-shadow).	false
fadeSpeed	How fast (in ms) to fade out the options menu on close.	200
state	New in 0.5! The default state of the widget. Either open or closed.	closed
disabled	New in 0.5! Whether or not to disabled the widget by default. Important: see the “Known Issues” section below for more documentation on this.	false
onCheck	A callback to fire when a checkbox is checked.	Function
onOpen	A callback to fire when the options menu is opened.	Function
onCheckAll	A callback to fire when the “Check all” link is clicked.	Function
onUncheckAll	A callback to fire when the “Uncheck all” link is clicked.	Function
onOptgroupToggle	A callback to fire when the opgroup header is clicked. An array of checkboxes inside the optgroup is passed as an optional argument.	Function

Known Issues

A few issues are still outstanding:

No onClose callback yet.
The position should automatically change if the current position will prevent the options menu from showing. E.g., if the input is at the bottom of the page, the options should appear not appear below the input.
In IE, the shadow parameter increases the width and height of the container, rendering it a few pixels wider than the input and throwing off the alignment. You can easily edit the CSS file and remove the IE-specific shadow filters, however, or opt not to use it.
If the select box you’re transforming into a multiselect is disabled, the option tags will actually inherit the disabled property only in webkit; Firefox and IE do not display this behavior. I’ve filed a bug on this. Therefore, to be cross-browser compatible, if the entire widget is disabled by default, the class ui-state-disabled is applied and the disabled attribute is removed. This is important to note because checkbox values could be transmitted during submit, even if the select is disabled. To toggle disabled state, toggle the ui-state-disabled class on the widget.
This bug does NOT effect the disabled state of specific option tags.

vZhai: Info Sharing Blog