Chosen for GWT

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

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.

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

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

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