jQuery Dropdown Check List

The Dropdown CheckList jQuery widget transforms a regular <SELECT> html element into a combo box with a text display of the selected elements and a dropdown of options. The plugin is hosted on SourceForge.
Dropdown Check List
The widget uses standard jQuery processing to select the target <SELECT> elements (matching on class or id or whatever) and replacing them with a single line text display that supports a dropdown list of options. The dropdown list is composed of checkboxes for multi-select elements, and radio buttons for single-select elements. Option groups are supported as well.

Copyright © Adrian Tosca; Ittrium, LLC; W.C.Omohundro

Licensed like jQuery, see http://docs.jquery.com/Licensing.

Download

The current version v1.5 of Dropdown CheckList can be downloaded from SourceForge Files. This page, including all required files to run the examples, can be downloaded as zip package from this location.

Requirements/Environments

Dropdown CheckList 1.5 requires the jQuery javascript support libraries (both core and ui), using jquery core version 1.11.2 and ui version 1.11.2.
For CSS styling, it can run as a stand-alone with custom CSS that you provide, or the preferred method is to leverage the jQuery ThemeRoller support. Dropdown CheckList uses element tags that match those defined by ThemeRoller. This page is styled with the ThemeRoller "smoothness" theme.

The widget has been tested with browsers

How does it work?

Dropdown CheckList uses the existing structure of the html select elements on which it is applied to dynamically build a container with checkboxes and labels, then hides the original select element. The plugin does not change in any way the existing select element, it only synchronizes the checked values from the new container to the original select. This approach has the added benefit to allow the use of the plugin with any server technology.

The widget will hide the existing select element by modifying its display attribute to none. The new widget will keep the replaced select options synchronized with the checkbox list so the postback is not affected. The text of the control is composed on the concatenated text of selected options in the list. Because the width of the control will not always accommodate all selected options, the control will show the full text on hover by updating its title attribute.

Samples / Tests

More tests that exercise various configuration options can be viewed here.
A simple sample/setup page can be viewed here.
A sample/setup page without ThemeRoller can be viewed here.

Examples

Simple Multi-selector

Nothing originally selected
$("#s1").dropdownchecklist();

Multi-selector with initially selected options and icons

The existing select element already has some options selected. In this case the widget will take over the selection automatically on initialization.
In addition, the ThemeRoller icon support is leveraged to include graphical markers on the widget.
$("#s2").dropdownchecklist( {icon: {}, width: 150 } );

Long text, shorter control

The 'width' option allows you to set a fixed width on the control even if the dropdown list is wider. The dropdown will keep its size so the items in the list are correctly visible.
$("#s3").dropdownchecklist({ width: 150 });

Long list of options, with scroll and disabled items

The 'maxDropHeight' option allows you to set a height for the dropdown list. This is useful when there is a big number of items. The dropdown list is scrollable to allow selection of all the items. Some select options have been disabled.
$("#s4").dropdownchecklist({ maxDropHeight: 150 });

Option to let the first item in list check all items

The 'firstItemChecksAll' option allows you to attach a special behavior to the first item in the list. If the item is checked, all items in the list are checked.
The 'explicitClose' option allows you to include a special close action as the last item in the list.
$("#s5").dropdownchecklist({ firstItemChecksAll: true, explicitClose: '...close' });

Select with groups

The existing select element has groups (optgroup elements). The options are listed in groups as with original select element.
$("#s6").dropdownchecklist();

Single select with radio buttons instead of checkboxes

If the select element does not have an multiple attribute then the plugin will display radiobuttons in the list.
$("#s7").dropdownchecklist();

Empty default text

The 'emptyText' options allows you to set the text can be displayed when no items are selected.
Note also that styling attributes applied to the OPTIONs are copied into the generated label components.
$("#s8").dropdownchecklist({ emptyText: "Please select ...", width: 150 });

Function for formatting the displayed text

The 'textFormatFunction' option allows you to supply a formatting function used to display the control text. You can then customize the text display in any way you wish. The callback function is run with a single argument that is the list of selector options. 
    $("#s9").dropdownchecklist({ textFormatFunction: function(options) {
        var selectedOptions = options.filter(":selected");
        var countOfSelected = selectedOptions.size();
        var size = options.size();
        switch(countOfSelected) {
           case 0: return "<i>Nobody<i>";
           case 1: return selectedOptions.text();
           case options.size(): return "<b>Everybody</b>";
           default: return countOfSelected + " People";
        }
    } });

Callback handling for both single item click and when the user completes their selection

The 'onComplete' option allows you to supply a callback function that is invoked when the user completes their selection and closes the dropdown. It is passed a single argument which is the original selector element.
The 'onItemClick' callback function can be defined to respond every time a user clicks on an item.
Also, you can force the target selector into multiple selection mode by using the 'forceMultiple' option, even if the underlying <SELECT> is not marked as multiple. -- The forceMultiple option does NOT work with IE 6 -- 
    $("#s10").dropdownchecklist( { forceMultiple: true
    , onComplete: function(selector) {
        var values = "";
        for( i=0; i < selector.options.length; i++ ) {
            if (selector.options[i].selected && (selector.options[i].value != "")) {
                if ( values != "" ) values += ";";
                values += selector.options[i].value;
            }
        }
	  	alert( values );
    } 
	, onItemClick: function(checkbox, selector){
		var justChecked = checkbox.prop("checked");
		var checkCount = (justChecked) ? 1 : -1;
		for( i = 0; i < selector.options.length; i++ ){
			if ( selector.options[i].selected ) checkCount += 1;
		}
	    if ( checkCount > 3 ) {
			alert( "Limit is 3" );
			throw "too many";
		}
	}
        });

Changing the original select element content or selection

The plugin does not automatically synchronize any changes made to the original select back into the DDCL checkboxes after initial creation. If the original select needs to change, for example by adding some options, changing the text, or reordering, then the plugin must be destroyed and recreated to reflect the changes:

$("#s1").dropdownchecklist("destroy");
$("#s1").val(...) // do something to the original select, for example select some options or change the options
$("#s1").dropdownchecklist();

If the changes you wish to make to the original selector are simple adjustments to the selected state or the disabled state (no changing the text, adding items, moving items, or deleting items), then you have a simplier (and faster) option to refresh the DDCL control without destroying it:

$("#s1").val(...) // do something to the original select, for example, changing which items are selected
$("#s1").dropdownchecklist("refresh");

Style

All components constructed by Dropdown CheckList are 'well named' in terms of classes for CSS styling. You can choose to develop your own CSS, but the recommended method of applying style is to leverage the settings provided by JQuery ThemeRoller. By including the CSS for a given ThemeRoller theme, the Dropdown CheckList widget will match that theme's look.

This page is styled using the ThemeRoller 'smoothness' theme.

Configuration Options

bgiframe: true/false
This option should be set to `true` if the user wants to use the bgiframe plugin (http://docs.jquery.com/Plugins/bgiframe)
@deprecated - I have no real knowledge of this feature and it is not included in any test
closeRadioOnClick: true/false
When true, a single selector with radio button display will close the dropdown when any radio button is clicked.
For backwards compatibility, the default is 'false' so you must explicitly include this option in your configuration as 'true' if you want the control to auto-close.
emptyText: 'string'
The emptyText option supplies the string to display if no options are currently selected. This string can include html formatting.
explicitClose: 'string'
The explicitClose option creates a special item at the end of the list that the user can click on to close the control. This string can include html formatting.
firstItemChecksAll: true/false/'exclusive'
The firstItemChecksAll option indicates if the first item in the list acts as the all/nothing option. If set to 'exclusive', then when the first item is checked, than all others are automatically unchecked.
forceMultiple: true/false
The forceMultiple option, when true, will treat the selector as having multiple selections even if the underlying html is not so marked.
This option does NOT work with IE 6
icon: { keyed-list }
The icon option allows you to include a ThemeRoller icon in the text display area. An empty list activates the icon with all default values, which are left placement, and the east/south triangles as the icons. The allowed options in the keyed-list are:
  • placement: 'left' or 'right'
  • toOpen: 'string name of ThemeRoller icon' (default is 'ui-icon-triangle-1-e')
  • toClose: 'string name of ThemeRoller icon' (default is 'ui-icon-triangle-1-s')
maxDropHeight: integerValue
The maxDropHeight option specifies the maximum height in pixels that the dropdown display is allowed to reach. Dropdowns taller than this maximum will have scrolling activated.
NOTE that it is best to include a 'width' when using maxDropHeight to leave space for vertical scroll bars.
minWidth: integerVaue
The minWidth option specifies the minimum width in pixels of the text display area. The width is only applied if there is no explicit 'width' value and if the calculated width of the option items is less than the minimum.
onComplete: function(selector) {}
The onComplete option defines a callback function invoked when the user is finished making their selections and then closes the dropdown. It is called with a single argument which is the underlying html <SELECT> element.
It would be desirable to use the standard 'blur' processing on the selector, but I have not been able to get blur to fire. If anyone has insight into this issue, please post an issue to help me out.
onItemClick: function(checkbox,selector) {}
The onItemClick option defines a callback function invoked when the user clicks on any item. It is called with two arguments:
  1. the dynamically generated checkbox element
  2. the original html selector

Note that when the callback is invoked, the checkbox has been set by user action, but the underlying selector option has not yet been adjusted.
The callback can 'reject' the click by throwing any error.
positionHow: 'absolute' or 'relative'
The positionHow option controls how the pop-up is positioned on the page. If 'absolute' (the default), then the pop-up is positioned absolutely to ride over the normal page contents. If 'relative', then the pop-up is included within the page contents, relative to its parent container. It consumes space on the page rather than flying over it, but it will scroll if the parent element is scrolled (Except for IE6 and IE7).
textFormatFunction: function(options) { return 'string'; }
The textFormatFunction option defines a callback function used to format the display text. It is called with a single argument that is the list selector options. The return string can include html formatting.
width: integerValue
The width option specifies the desired width in pixels of the text display area. If not given, the width is calculated from the width of the option items. The width may be wider than the items, to provide extra room for icons or the display of multiple items. The width may be narrower than the items to account for dropdowns with very long names.
zIndex: integerValue
The zIndex option specifies the explict z-index value to apply to the pop-up container, to help it display properly with other components on the page. This is of particular value if you have other active jQuery widgets.

Use of IDs

Dropdown CheckList generates two basic components that are inserted into the document. There is a control wrapper which is positioned in place of the original selector and acts like the <select> item on the page. And there is the drop-down wrapper which is only visible when the control wrapper is 'open' and is positioned under the control.

Both of these items are assigned an id, which you can use in other jQuery processing to locate and alter the items.

Control Wrapper
The control wrapper has a generated id of the form "ddcl-XXX", where the XXX is either 1) the assigned id of underlying <select>, or 2) an incrementing counter when the <select> has no id assigned.
Drop-down Wrapper
The drop-down wrapper has a generated id of the form "ddcl-XXX-ddw", where the XXX matches the XXX of the control wrapper.
These ids must be unique and Dropdown CheckList assumes no other elements on the page have an id that conflicts.

Limitations

History

Version 1.5
  • Compatibility with jQuery 1.11
Version 1.4
  • Compatibility with jQuery 1.6
  • Expancded onItemClick support
  • 'exclusive' first item checks all
Version 1.3
  • Recognize 'styled' options and other explicit text
  • onItemClick support
Version 1.2 (never made it out of QA)
  • Correct positioning problems with relative parent
  • explicitClose option
  • zIndex option
Version 1.1
  • jQuery 1.4.2, jQuery ui 1.8.4
  • "refresh" function to synch DDCL control with simple selected/disabled changes made to underlying <select>
Version 1.0
  • jQuery 1.3.2, jQuery ui 1.7.2
  • ThemeRoller based styling
  • better support for multiple controls on single page

Have problems using the plugin?

Have a look at the SourceForge Ticketing system. You may want to search through 'closed' as well as 'open' issues in case an issue has been identified as something we choose not to fix.