Using Select With a List
The documentation for the Select Component and the Tapestry Tutorial provide simplistic examples of populating a drop-down menu (as the (X)HTML Select element) using comma-delimited strings and enums. However, most real-world Tapestry applications need to populate such menus using values from a database, commonly in the form of java.util.List objects. Doing so generally requires a SelectModel and a ValueEncoder bound to the Select component with its "model" and "encoder" parameters:
In the above example, ColorSelectModel must be of type SelectModel, or anything that Tapestry knows how to coerce into a SelectModel, such as a List or a Map or a "value=label,value=label,..." delimited string, or anything Tapestry knows how to coerce into a List or Map, such as an Array or a comma-delimited String.
A SelectModel is a collection of options (specifically OptionModel objects) for a drop-down menu. Basically, each option is a value (an object) and a label (presented to the user).
If you provide a property of type List for the "model" parameter, Tapestry automatically builds a SelectModel that uses each object's toString() for both the select option value and the select option label. For database-derrived lists this is rarely useful, however, since after form submission you would then have to look up the selected object using that label.
If you provide a Map, Tapestry builds a SelectModel that uses each item's key as the encoded value and its value as the user-visible label. This is more useful, but if you are going to build a copy of the list as a map just for this purpose, you may as well let Tapestry do it for you, using SelectModelFactory.
To have Tapestry create a SelectModel for you, use the SelectModelFactory service. SelectModelFactory creates a SelectModel from a List of objects (of whatever type) and a label property name that you choose:
The resulting SelectModel has a selectable option (specifically, an OptionModel) for every object in the original List. The label property name (the "name" property, in this example) determines the user-visible text of each menu option, and your ValueEncoder's toClient() method provides the encoded value (most commonly a simple number). If you don't provide a ValueEncoder, the result of the objects' toString() method (Color.toString() in this example) is used. In principle, you could set your toString() to return the object's ID for this purpose:
But then, that is a contortion of the toString()'s purpose, and if you go to that much trouble you're already half way to creating a ValueEncoder.
While a SelectModel is concerned only with how to construct a Select menu, a ValueEncoder is used when constructing the Select menu and when interpreting the encoded value that is submitted back to the server. A ValueEncoder is a converter between the type of objects you want to represent as options in the menu and the client-side encoded values that uniquely identify them, and vice-versa.
Most commonly, your ValueEncoder's toClient() method will return a unique id (e.g. a database primary key, or perhaps a UUID) of the given object, and its toValue() method will return the object matching the given id by doing a database lookup (ideally using a service or DAO method).
If you're using one of the database integration modules Tapestry-Hibernate, Tapestry-JPA (starting in Tapestry 5.3), or Tapestry-Cayenne ), the ValueEncoder is automatically provided for each of your mapped entity classes. The Hibernate module's implementation is typical: the primary key field of the object (converted to a String) is used as the client-side value, and that same primary key is used to look up the selected object.
That's exactly what you should do in your own ValueEncoders too:
Applying your ValueEncoder Automatically
If your ValueEncoder implements ValueEncoderFactory (as ColorEncoder does, above), you can associate your custom ValueEncoder with your entity class so that Tapestry will automatically use it every time a ValueEncoder is needed for items of that type (including for the Select component). Just add lines like the following to your module class (usually AppModule.java):
Skipping the ValueEncoder
If your Select's "value" parameter is bound to a complex object (not a simple String, Integer, etc.) and you don't provide a ValueEncoder with the "encoder" parameter (and one isn't provided automatically by, for example, the Tapestry Hibernate integration), you'll receive a "Could not find a coercion" exception (when you submit the form) as Tapestry tries to convert the selected option's encoded value back to the object in your Select's "value" parameter. To fix this, you'll either have to 1) provide a ValueEncoder, or 2) use a simple value (String, Integer, etc.) for your Select's "value" parameter, and then you'll have to add logic in the corresponding onSuccess event listener method:
But then again, you may as well create a ValueEncoder instead.
Why is this so Hard?
Why is Tapestry designed to use SelectModels and ValueEncoders anyway? Well, in short, this design allows you to avoid storing (via @Persist, @SessionAttribute or @SessionState) the entire (potentially large) list of objects in the session or rebuilding the whole list of objects again (though only one is needed) when the form is submitted. The chief benefit is more scalable clustering due to having less HTTP session data to replicate across the nodes of a cluster.