See SeamSelectItemsNewDesign
Download
Latest version: 1.1.0rc2, compatible with Seam 1.1BETA1 and 1.0.1.GA
Databinder
Exposes an attribute of type List as a List of JSF SelectItem into the scope of the owning component (or the EVENT scope if the owning component is STATELESS).
Core attributes
label - The name of the getter method to use for the label of the SelectItem.Defaults to the toString() value. By default a lookup on the Seam message bundle is done, with the label as the key.
addNoSelectionLabel - Add a 'Select One...' label to the top of <select>. The value of addNoSelectionLabel is looked up in the Seam message bundle.
Fine control attributes
strategy - Choose a strategy for automatic value conversion. Defaults to OBJECT. A suitable converter needs to be defined unless the object is a string (e.g. the Entity Converter or the Enum Converter)
jsfValue - The name of the getter method to use for the JSF value. Ignored usless strategy==Strategy.STRING, defaults to toString();
disabled - The name of the getter method to set the disabled property of the SelectItem. By default the SelectItem is enabled.
useMessageBundle - Defaults to true. If false the Seam message bundle is not used when creating labels.
Standard attributes for all DataBinders
value - name of the conversation context variable. Default to the attribute name.
scope - if scope=ScopeType.PAGE is explicitly specified, the List<SelectItem> will be kept in the PAGE context.
Strategy
Strategy is one of OBJECT (default), INDEX or STRING. OBJECT is the recommended strategy; INDEX and STRING are useful for non-standard cases.
OBJECT - The OBJECT strategy indicates that the rendered JSF value should be the actual original item object. This requires a custom converter; the provided EntityConverter can be used if the list is a list of entities, or, the provided EnumConverter for an enumeration.
INDEX - The INDEX strategy indicates that the rendered JSF value should be the index of the original list item.
STRING - The STRING strategy indicates that the rendered JSF value should be a String. The property to use to get the value is specified using the jsfValue attribute.
The object strategy is simple to use:
public class FormActionBean {
...
@SelectItems(label="description", addNoSelectionLabel="Select One...", cacheKey="formActionGroups")
List groups;
...
@Factory("groups")
public void buildGroups () {
// Load the groups to be in the list from persistence
// Do any processing required on the list
}
...
}
@Entity
public class Group {
@Id Integer id;
String description;
...
// Getters and Setters
}
addNoSelectionLabel="..."
This causes a SelectItem with a null value to be added to the top of the list, with the provided label. Using required="true" on the JSF component requires an option to be selected (other than the label).
Taglib
si is the prefix for the http://jboss.com/products/seam/selectitems/taglib namespace. Three tags are supported (in facelets only) - convertEntity, convertEnum and selectItems and there are two converters org.jboss.seam.EntityConverter and org.jboss.seam.EnumConverter (can be used in JSP as well).
Caching
This requires the use of si:selectItems instead of the standard f:selectItems. It has two additional attributes - cacheKey="..." and cacheRegion="...".
cacheKey - Enable caching support (using pojoCache support in Seam). This is useful for dropdowns whose value does not change much over time (e.g. a list of nationalities, a list of honorifics). The cacheKey is used as a key for the cache.
cacheRegion - Override the default (org/jboss/seam/selectitems) cache region. Only has an affect if cacheKey is set.
The jgroups.jar and jboss-cache.jar need to be added to your ear, and the cache configuration file treecache.xml should be added to the root of the ear. A sample (non-clustered) can be found in the example app. The default region (allows control of cache content expiration etc.) is org/jboss/seam/selectitems. This can be overridden by using the cacheRegion attribute on si:selectItems.
EntityConverter
This is a generic JSF converter to allow already persisted EJB3 Entity objects to be used as the value in a dropdown.
You must configure the Persistence Unit to use in components.xml:
<component class="org.jboss.seam.selectitems.SelectItemsConfig"> <property name="persistenceUnitJndiName">java:/selectItemsEntityManagerFactory</property> </component>
To use it:
<h:selectOneListbox value="#{user.group}" converter="org.jboss.seam.EntityConverter">
<f:selectItems value="#{groups}" ></f:selectItems>
</h:selectOneListbox>
or, if you use facelets you could do:
<h:selectOneListbox value="#{user.group}">
<f:selectItems value="#{groups}" ></f:selectItems>
<si:convertEntity ></si:convertEntity>
</h:selectOneListbox>
si:convertEntity has two attributes: entityClass="..." allows you to override the entity class to look up, persistenceUnitJndiName="..." allows you to use another persistence context than the default.
EnumConverter
This converts Enum's for a <select>. To use it:
<h:selectOneListbox value="#{user.honorific}" converter="org.jboss.seam.EnumConverter">
<f:selectItems value="#{honorifics}" ></f:selectItems>
</h:selectOneListbox>
where honorifics is a List of Enum's and user.honorific is an Enum of the same type.
Example
The example shows the use of @SelectItems and the EntityConverter; in the example directory type ant deploy. It also shows use of the EnumConverter, the EntityConverter in a select many (only working with Facelets currently, and the entityClass specified on the converter tag), and a 'Please Select...' label which if selected causes validation to fail.
Tips and Troubleshooting
If you find that your @SelectItems annotated fields are mysteriously null or fail to outject the right type, make sure you have only one copy of the selectitems.jar in your project. For EJB3 apps, put the jar it in the .ear and reference it as a module from application.xml (see the example). You can also reference it in the classpath of the jar MANIFEST.MF.
Value is not valid: JSF will validate the drop down by ensuring the item selected is in the original list. As the EntityConverter loads a new object from the database the selection doesn't have object equality. Using Id equality on all entities which gets around this (see the overrided equals for ClientType in the example).
Select Many: This is requires a trick; use the entityClass attribute of the <convertEntity> to specify the qualified class name of the entity being selected. The EntityConverter is unable to guess the entity class in this case.
Future work
@SelectItemsSelection
Improve the select many support in EntityConverter
Changelog
1.1.0rc2
FEATURE Add convertEnum tag for facelets
FEATURE Added caching support. This is based on the pojoCache component of Seam.
Rename org.jboss.seam.selectitems.SelectItemsPersistenceConfig to org.jboss.seam.selectitems.SelectItemsConfig. THIS IS A BREAKING CHANGE.
1.0.1rc1 to 1.1.0rc1
Make compatible with Seam 1.1BETA1
1.0rc4 to 1.0.1rc1
FEATURE: Patch from Mikko Koponen to support 'noSelectionLabel'. This places a SelectItem at the top of the list which has a value null. Combined with the use of required="true" this allows the UI to force the user to select a value from the list.
BUG FIX: Patch from Mikko Koponen to correct error in jsfValue (Thanks to others for spotting this)
BUG FIX: Patch from Mikko Koponen to search superclasses for @Id (Thanks also to Jarkko for finding the bug)
FEATURE: Use of Seam Messages resource bundle. By default any label is interpreted as a key for the Seam message bundle. As usual with the Seam message bundle if the key/value pair isn't defined the key is used.
FEATURE: An EnumConverter to complement the EntityConverter
BUG FIX: Example upgraded to show new features
BUG FIX: Upgrade Ant Build to support build numbers
FEATURE: Move homepage of project to Seam Wiki SeamSelectItems
1.0rc3 to 1.0rc4
@SelectItems Binder altered so that the getter methods for label, jsfValue and disabled must be public. They may also be on the superclass.
Multiple selection example and fix
See also
You can do this without annotations
Comments