Fork me on GitHub

Chosen for GWT

Chosen is a javascript plugin (for jQuery and Prototype) that makes long, unwieldy select boxes much more user-friendly. GwtChosen is a port of the jquery version of Chosen for Google Web Toolkit. It is not a wrapper but a complete rewrite using the GWT standards. It is available as a GwtQuery plugin or as a widget.

Chosen allows you to turn this single select element:

into a more user-friendly component like this:

Or this multiple select element:

into:

With one line of java code :

import static com.google.gwt.query.client.GQuery.$;
import static com.watopi.chosen.client.Chosen.Chosen;
...	
$(".selectToEnHance").as(Chosen).chosen();
					

In addition to the GwtQuery way to call the plugin, you have the possiblility to use the ChosenListBox widget either in your uibinder template :

<!DOCTYPE ui:UiBinder SYSTEM "http://dl.google.com/gwt/DTD/xhtml.ent">
<ui:UiBinder ...
	xmlns:chzn="urn:import:com.watopi.chosen.client.gwt">
	<chzn:ChosenListBox maxSelectedOptions="5" placeholderText="Choose your country...">
			<g:item value=""></g:item>
			<g:item value="United States">United States</g:item>
			<g:item value="United Kingdom">United Kingdom</g:item>
			...
	</chzn:ChosenListBox>

or directly in your java code :

import com.watopi.chosen.client.gwt.ChosenListBox;
...

ChosenListBox chzn = new ChosenListBox(true);
chzn.addItem("United States");
chzn.addItem("United Kingdom");
...
chzn.setMaxSelectedOptions(5);
chzn.setPlaceholderText("Choose your country...");

Check this complete example for more code

Single select with groups

Multiple select with groups

The ChosenListBox supports the optgroups as well:

//add a optgroup
chzn.addGroup("NFC EAST");
//insert a optgroup in a specific position
chzn.insertGroup("NFC EAST", 2);
//add an item to the last optgroup
chzn.addItemToGroup("Dallas Cowboys");
//add an item at the end to the second optgroup
chzn.addItemToGroup("Chicago Bears", 1);
//insert the item in the 4th position of the second optgroup 
chzn.insertItemToGroup("Dallas Cowboys", 1, 3);

Chosen automatically highlights selected options and removes disabled options.

Single select

Multiple select

The Chosen plugin can be configured by using an instance of the class ChosenOptions

ChosenOptions options = new ChosenOptions();
options.setAllowSingleDeselect(true);
//set the options you want...
$("select").as(Chosen).chosen(options);

//to retrieve the options later
ChosenOptions options = $("#myselect").as(Chosen).options();

If you are using the ChosenListBox widget, it offers needed methods for configuring it.

ChosenListBox chzn = new ChosenListBox();
chzn.setAllowSingleDeselect(true);
//...

Default Text Support

Chosen automatically sets the default field text ("Choose a country...") by reading the select element's data-placeholder value. If no data-placeholder value is present, it will default to "Select Some Option" or "Select Some Options" depending on whether the select is single or multiple. You can change these default texts via the options

If you have access to the select html element:

<select data-placeholder="Choose a country..." style="width:350px;" multiple class="chzn-select">

or via the ChosenOptions object:

ChosenOptions options = new ChosenOptions();
options.setPlaceholderTextSingle("Choose a country...");
options.setPlaceholderTextMultiple("Choose countries..."); 

//using the widget
ChosenListBox chzn = new ChosenListBox();
chzn.setPlaceholderTextSingle("Choose a country...");

Note: on single selects, the first element is assumed to be selected by the browser. To take advantage of the default text support, you will need to include a blank option as the first element of your select list.

List of options

The table below lists the different properties of the ChosenOptions . Each property is accessible via getter/setter methods.

Property name Type Description Default Example
allowSingleDeselect boolean When a single select box isn't a required field, you can set allowSingleDeselect to true and an UI element will be added for option deselection. This will only work if the first option has blank text. false

allowSingleDeselect = true

disableSearchThreshold int If the number of options is less than or equal to the disableSearchThreshold, the search box is disabled. 0

disableSearchThreshold = 10

searchContains boolean If searchContains equals false, search will only match words starting with the query entered by the user. Otherwise, the search will match words containing the query. false

searchContains = true

singleBackstrokeDelete boolean Indicates if a choice from a multiple select box can be deleted by pressing one backspace. If this option is set to false (default), the first backspace selects the last choice, the second removes it. false

singleBackstrokeDelete = true

maxSelectedOptions int Defines the maximum number of options that can be selected in a multiple select box. if this option is set to -1, the user can select as many options as he wants. -1

maxSelectedOptions = 5

noResultsText String Defines the text to display when the query entered by the user doesn't match any options. No results match

noResultsText = "Ooops, nothing was found"

Chosen fires a number of events that you can listen for.

Event name Description Properties
ChosenChangeEvent Event fired when the user selects or deselects an option.
  • isSelection() returns a boolean indicating if the event was fired on a selection (true) or a deselection (false)
  • getValue() returns the selected or deselected value (can be null)
HidingDropDownEvent Event fired when the drop down is hiding.
MaxSelectedEvent Event fired when the maximum number of options defined by the option maxSelectedOptions is reached on a multiple select box.
ReadyEvent Event fired when all html defining the chosen component is ready.
ShowingDropDownEvent Event fired when the drop down is showing.

GwtChosen uses the GWT event system for firing these events. In order to listen to them, you have to pass an instance of com.google.web.bindery.event.shared.EventBus when you call chosen:

EventBus eventBus = new SimpleEventBus();
eventBus.addHandler(HidingDropDownEvent.getType(), new HidingDropDownHandler() {

  public void onHidingDropdown(HidingDropDownEvent event) {
    // Do something when choices are hiding
  }
});
$(".chzn-select, .enhance").as(Chosen).chosen(eventBus);

The ChosenListBox widget exposes needed method for listening to the events:

ChosenListBox chzn = new ChosenListBox();
    
chzn.addHidingDropDownHandler(new HidingDropDownHandler() {

  public void onHidingDropdown(HidingDropDownEvent event) {
    // Do something when choices are hiding
  }
});

Check this example in order to know how and when the different events are fired.

If you need to update the options in your select field and want Chosen to pick up the changes, you'll need to prevent the component in order to re-build itself based on the updated content.

with GQuery:

//add an option
$("#mySelect").append($("<option></option>").attr("value","myNewOption").text("My new option"));
$("#mySelect").as(Chosen).update();

with the ChosenListBox widget:

//let's assume that myChosenListBox is an instance of ChosenListBox
myChosenListBox.addItem("My new option","myNewOption");
myChosenListBox.update();

Example:

All modern browsers are supported (Firefox, Chrome, Safari and IE9). Legacy support for IE8 is also enabled. On IE6 and IE7, we fall back on normal html select element.

To know if the use's browser is supported by the plugin, you can call the isSupported() method :

boolean chosenSupport = Chosen.isSupported();
//or 
boolean chosenSupport = ChosenListBox.isSupported();
					

GwtChosen depends on GwtQuery. You need at least GwtQuery 1.2. Please follow the instructions to download GwtQuery jar file and put it in your classpath.

With maven

Add the following block to your pom.xml

<repositories>
	<repository>
		<id>plugins</id>
		<url>http://gwtquery-plugins.googlecode.com/svn/mavenrepo</url>
	</repository>
</repositories>

<build>
	<dependencies>
		<dependency>
        	<groupId>com.watopi</groupId>
            <artifactId>gwtchosen</artifactId>
            <version>1.1.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</build>	
   	

Without maven

Download the last stable jar file and put it in your claspath.

Then you need to inherit the plugin in your Module.gwt.xml file:

<inherits name='com.watopi.chosen.Chosen'/>
					

The initial chosen javascript plugin was built by Harvest. Concept and development by Patrick Filler. Design and CSS by Matthew Lettini

The GWT port of Chosen was built by Julien Dramaix