wicket-user-guide/src/docs/guide/modelsforms/modelsforms_4.gdoc

Class @org.apache.wicket.markup.html.form.DropDownChoice@ is the form component needed to display a list of possible options as a drop-down list where users can select one of the proposed options. This component must be used with <select> tag:

Html:

{code:html}
<form wicket:id="form">
	Select a fruit: <select wicket:id="fruits"></select>
<div><input type="submit" value="submit"/></div>
</form>
{code}

Java code:

{code}
List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); 
form.add(new DropDownChoice<String>("fruits", new Model(), fruits));
{code}

Screenshot of generated page:

!dropdown-choice.png!

In addition to the component id, in order to build a DropDownChoice we need to provide to its constructor two further parameters:

* a model containing the current selected item. This parameter is not required if we are going to inherit a CompoundPropertyModel for this component.
* a list of options to display which can be supplied as a model or as a regular java.util.List.

In the example above the possible options are provided as a list of String objects. Now let's take a look at the markup generated for them:

{code:html}
<select name="fruits" wicket:id="fruits">
	<option value="" selected="selected">Choose One</option>
	<option value="0">apple</option>
	<option value="1">strawberry</option>
	<option value="2">watermelon</option>
</select>
{code}

The first option is a placeholder item corresponding to a null model value. By default DropDownChoice cannot have a null value so users are forced to select a not-null option. If we want to change this behavior we can set the nullValid flag to true via the setNullValid method. Please note that the placeholder text (“Chose one”) can be localized, as we will see in chapter 15. The other options are identified by the attribute value. By default the value of this attribute is the index of the single option inside the provided list of choices, while the text displayed to the user is obtained by  calling toString()on the choice object. This default behavior works fine as long as our options are simple objects like strings, but when we move to more complex objects we may need to implement a more sophisticated algorithm to generate the value to use as the option id and the one to display to user. Wicket has solved this problem with @org.apache.wicket.markup.html.form.IChoiceRender@ interface. This interface defines method getDisplayValue(T object) that is called to generate the value to display for the given choice object, and method getIdValue(T object, int index) that is called to generate the option id. The built-in implementation of this interface is class @org.apache.wicket.markup.html.form.ChoiceRenderer@ which renders the two values using property expressions.

In the following code we want to show a list of Person objects using their full name as value to display and using their passport code as option id: 

Java code:

{code}
List<Person> persons; 
//Initialize the list of persons here...
ChoiceRenderer personRenderer = new ChoiceRenderer("fullName", "passportCode");
form.add(new DropDownChoice<String>("persons", new Model<Person>(), persons, personRenderer));
{code}

The choice renderer can be assigned to the DropDownChoice using one of its constructor that accepts this type of parameter (like we did in the example above) or after its creation invoking setChoiceRenderer method.