Version 10

    This is now in Seam from the 1.2.1.GA release.

     

    Download

    Latest version: 0.1-draft, compatible with > Seam 1.1.5.GA

     

    -


     

    Getting Started Guide - Using s:selectItems & ec:convertEntity with EJB3 Entities

     

    1. Download and Configure SeamEntityConverter

      1. Download the entityconverter-0.1.zip, and unzip it.  Included are prebuilt jars, source code and an example

      2. Place entityconverter.jar in the WEB-INF/lib of your war

      3. Make sure you have a Seam-managed persistence context set up (see Chapter 8.3.1 of the reference documentation) with entityManager as the name, and are using it to manage your entities.

    2. Ensure your Entity Beans and Action beans are setup correctly

      1. Make sure you have the correct relationships between your entities (i.e. use the @ManyToOne, @OneToOne etc. annotations)

      2. Make sure you are outjecting a list of entities (NOT a List<SelectItem>)

    3. Alter your page

      1. Include the taglibrary definition in your page.  The uri of the taglibrary is http://jboss.com/products/seam/entityconverter/taglib but its broken!.

        1. If you are using facelets add xmlns:ec="http://jboss.com/products/seam/entityconverter/taglib" to your root tag (probably ui:composition)

        2. If you are using JSP add <%@ taglib uri="http://jboss.com/products/seam/entityconverter/taglib" prefix="ec"%> to the top of the file

      2. Add a select JSF component (e.g. h:selectOneMenu)

      3. Make sure you use s:selectItems rather than f:selectItems (see Code Block 1 below)

        1. Add the value attribute, with an EL expression referencing the outjected list you want to display

        2. Add the var attribute; this must be a static text variable

        3. Add the label attribute to set the label for each item in the dropdown.  You will probably want to reference the var attribute

        4. Add the <ec:convertEntity /> tag to the

     

    Code Blocks

     

    Code Block 1: Example use of si:selectItems

    <h:selectOneMenu value="#{user.nationality}">
       <s:selectItems value="#{nationalities}" var="nationality" label="#{nationality.label}" ></s:selectItems>
       <ec:convertEntity ></ec:convertEntity>
    </h:selectOneMenu>

     

    -


     

    Examples Explained

     

    The examples show a number of common cases for the use of SeamEntityConverter.  The example code described here applies equally to the facelets and the jsp example.  Make sure you look at the example code when reading this section!

     

    ClientType

     

    <h:selectOneListbox value="#{client.clientType}">
       <s:selectItems value="#{clientTypes.resultList}" var="clientType" label="#{clientType.description}" noSelectionLabel="Please Select..." ></s:selectItems>
       <ec:convertEntity ></ec:convertEntity>
    </h:selectOneListbox>
    

     

    ClientType shows the standard use of ec:convertEntity with s:selectItems/

     

    Factory

     

    <h:selectManyListbox value="#{client.factories}">
       <s:selectItems value="#{factories.resultList}" var="factory" label="#{factory.manager} (#{factory.capacity})" ></s:selectItems>
       <ec:convertEntity entityClass="org.jboss.seam.example.entityconverter.Factory" ></ec:convertEntity>
    </h:selectManyListbox>
    

     

    Factory is a select many, which works just as a select one.  Note, that due to a limitation in the entityConverter you must specify the class of the entity to be converted.

     

    Using EJB-Queries with s:selectItems

     

    The combination of s:selectItems, ec:convertEntity and Seam's EntityQuery's from the Seam Application framework is really powerful. Imagine you have these entities:

     

    @Entity
    public class Department {
    
       @Id
       private Integer id;
       private String name;
       // other properties
    
       // getters & setters
    }
    

     

    @Name("employee")
    @Scope(CONVERSATION)
    @Entity
    public class Employee {
    
       @Id
       private Integer id;
    
       @ManyToOne
       private Department department;
       // other properties
      
       // getters & setters
    
    }
    

     

    If you create or edit the record of an employee, you want to set the department. This list of available departments has to be fetched from the database. You can do this by defining a query object in components.xml:

     

    <framework:entity-query name="departments" ejbql="select d from Department d" ></framework:entity-query>
    

     

    Now you can use the seam component "departments" with the s:selectitems tag:

     

    <h:selectOneMenu value="#{employee.department}">
       <s:selectItems value="#{departments.resultList}" var="department" label="#{department.name}"></s:selectItems>
       <ec:convertEntity ></ec:convertEntity>
    </h:selectOneMenu>
    

     

    -


     

    Reference Guide

     

    Taglibrary

     

    • s:convertEntity Attaches the org.jboss.seam.EntityConverter to the Select{One, Many}

      • entityClass attribute sets the class of the entities being converted. Only required if the converter is having problems guessing the class. (static value only)

     

    Converters

     

    • org.jboss.seam.EntityConverter - A generic converter which can deal with all objects marked with @Entity which have primitive, primitive-wrapped or String ids.

     

    Abstract Converters

    • org.jboss.seam.entityconverter.AbstractEntityConverter. This converter will do most of the work if you have a more complex id. You just need to:

      • Override getIdAsString, and provide conversion from the entities Id to a string

      • Override getIdAsObject, and provide conversion from a string back to an Id

     

    Configuration through components.xml

     

    You can change the EntityManager used in conversion by altering the lookup component used in components.xml:

     

    <component name="org.jboss.seam.entityconverter.lookup">
       <property name="entityManager">#{myEntityManager}</property>
    </component>
    

     

    If you need to use different EntityManagers then you can configure an alternative:

     

    <component name="myLookup" class="org.jboss.seam.entityconverter.Lookup">
       <property name="entityManager">#{anotherEntityManager}</property>
    </component>
    

     

    <ec:convertEntity lookup="#{myLookup"} ></ec:convertEntity>
    

     

    Changelog

     

    0.1 - Initial release of fork from SeamSelectItemsNewDesign

     

    -


     

    Also

    • Original Design - SeamSelectItemsNewDesign