org.apache.tapestry.corelib.components.Select

Select an item from a list of values, using an [X]HTML select element on the client side. An validation decorations will go around the entire select element. A core part of this component is the org.apache.tapestry.ValueEncoder (the encoder parameter) that is used to convert between server-side values and client-side strings. In many cases, a org.apache.tapestry.ValueEncoder can be generated automatically from the type of the value parameter. The org.apache.tapestry.services.ValueEncoderSource service provides an encoder in these situations; it can be overriden by binding the encoder parameter, or extended by contributing a org.apache.tapestry.services.ValueEncoderFactory into the service's configuration.

[JavaDoc]

Component Inheritance

Component Parameters

NameTypeFlagsDefaultDefault PrefixDescription
blankLabelStringliteralThe label to use for the blank option, if rendered. If not specified, the container's message catalog is searched for a key, id-blanklabel.
blankOptionorg.apache.tapestry.corelib.data.BlankOptionautoliteralControls whether an additional blank option is provided. The blank option precedes all other options and is never selected. The value for the blank option is always the empty string, the label may be the blank string; the label is from the blankLabel parameter (and is often also the empty string).
clientIdStringprop:componentResources.idliteralThe id used to generate a page-unique client-side identifier for the component. If a component renders multiple times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the clientId property.
disabledbooleanfalsepropIf true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a disabled field ignores any value in the request when the form is submitted.
encoderorg.apache.tapestry.ValueEncoderpropAllows a specific implementation of org.apache.tapestry.ValueEncoder to be supplied. This is used to create client-side string values for the different options.
labelStringliteralThe user presentable label for the field. If not provided, a reasonable label is generated from the component's id, first by looking for a message key named "id-label" (substituting the component's actual id), then by converting the actual id to a presentable string (for example, "userId" to "User Id").
modelorg.apache.tapestry.SelectModelRequiredpropThe model used to identify the option groups and options to be presented to the user. This can be generated automatically for Enum types.
validateorg.apache.tapestry.FieldValidatorvalidatePerforms input validation on the value supplied by the user in the form submission.
valueObjectRequiredpropThe value to read or update.

Simple Example

A simple example, selecting one of three strings:

SelectColor.tml

<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
    <body>
        <h1>Select Color</h1>

        <t:form>

            <t:label for="color"/>:
            <t:select t:id="color" model="literal:Red,Green,Blue"/>

            <br/>

            <input type="submit" value="Continue"/>
        </t:form>

    </body>
</html>
When the model parameter is a string, it is split apart at the commas.

When using this approach, you'll commonly put the list into the message catalog, and reference it using a "message:" binding.

Here the label displayed to the user is the same as the value used to update the property, but that doesn't have to be the case. By specifying a value and a label, we can control the server side value without changing how the UI appears to the user: 

                    
            <t:select t:id="color" model="literal:FF0000=Red,00FF00=Green,0000FF=Blue"/>

SelectColor.java

public class SelectColor
{
  private String _color;

  @Validate("required")
  public String getColor() { return _color; }

  public void setColor(String color) { _color = color; }
}

Placing the @Validate annotation on the field indicates that it is required. This prevents the select component from including a blank option for the field (though this can be overridden). Without the @Validate, it would be possible for the user to select a blank value, and null would be assigned to the color property of SelectColor. This might be appropriate for a search form, but not for an edit form.

Enum Example

Working with Enums is, amazingly, even easier (and more so than with the Radio component).

Most of this example is the same as for the Radio component, except that we're using a single Select component instead of multiple Radio components:

CardType.java

public enum CardType
{
    MASTER_CARD, VISA, AMERICAN_EXPRESS, DINERS_CLUB, DISCOVER
}

Payment.tml (partial)

In the Radio example, we used a Label and a Radio component for each enum value. With Select we use a single Label and a single Select component: 

    <t:label for="type"/>:
    <t:select t:id="type"/>

Here again, Tapestry is binding the value parameter to the type property, based on the component's id. In addition, because the property type of the property in question is an enum, a SelectModel is automatically generated.

Payment.java (partial)

                                                                   
public class Payment
{
    . . .

    @Persist
    private CardType _type;

    @Validate("required")
    public CardType getType() { return _type; }

    public void setType(CardType type) { _type = type; }

    . . .
}

Payment.properties

Once again, we need to slightly customize Tapestry's guess at the label for the enum value DINERS_CLUB. In the Radio example, we overrode the label for the dinersClubcomponent. Here there is just the Select component, but we still have an option: override how the DINERS_CLUB enum value is displayed: 

DINERS_CLUB=Diner's Club

Tapestry looks inside a component's message catalog for entries before "humanizing" the name. In the very rare event that there's a naming conflict, you may qualify the enum value with its class name: 

CardType.DINERS_CLUB=Diner's Club

And, of course, all of this is case insensitive. The use of case here helps to identify how the values are to be used.

Back to index