org.apache.tapestry5.corelib.components.Select.xdoc Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of tapestry-core Show documentation
Central module for Tapestry, containing interfaces to the Java Servlet API and all core services and components.
There is a newer version: 5.8.6

    
        

            
                A simple example, selecting one of three strings:
            

            
                
    
        Select Color

        

            :
            

            


            
        

    
]]>

When the model parameter is a string, it is split apart at the commas. When the model parameter is
a List of Strings, each element is considered a selection option.


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:



]]>





Placing the @Validate annotation on the field supplies the default validation for this field, here
it indicates that color is required. This prevents the
Select component from including a blank option for the field (though this behavior too 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.




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:









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:

:
]]>

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.







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:


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:


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




There is often a requirement for chaining Select components. When a value of a Select component is changed
another Select should become visible. Let's consider the following example: you create an online shop for a car seller.
A make is modeled as enumeration CarMaker.




The Select component 'carMaker' of the page SelectZoneDemo shows all available car makers.
When a user selects a car maker, another Select component for selecting available models of the make should appear.
This can be accomplished by the parameter zone of the Select component 'carMaker'. When zone parameter is bound
every change of the Select's value causes an Ajax request. In this case the Select component publishes the event valuechanged which can
be used to provide the model for the second Select component.



















]]>


The event handler method for the event valuechanged is used to provide the available car models of the currently selected car maker.
The new Select's value is passed as context.
 availableModels;
public Object onValueChanged(CarMaker maker)
{
availableModels = findAvailableModels(maker);
return modelZone.getBody();
}
public List findAvailableModels(final CarMaker maker)
{
switch (maker)
{
case AUDI:
return Arrays.asList("A4", "A6", "A8");
case BMW:
return Arrays.asList("3 Series", "5 Series", "7 Series");
case MERCEDES:
return Arrays.asList("C-Class", "E-Class", "S-Class");
default:
return Arrays.asList();
}
}
}]]>

The Select component is very smart for enum types; it can automatically create a SelectModel for a given Enum, and a default
ValueEncoder. Likewise, it can turn an array or List into a SelectModel automatically. This streamlines the use of the Select
in many situations ... but because the model and encode parameters are still present, allows you to override its behavior
when needed.