SeamFramework.orgCommunity Documentation

Chapter 31. Seam JSF controls

31.1. Tags
31.1.1. Navigation Controls
31.1.2. Converters and Validators
31.1.3. Formatting
31.1.4. Seam Text
31.1.5. Dropdowns
31.1.6. Other
31.2. Annotations

Seam includes a number of JSF controls that are useful for working with Seam. These are intended to complement the built-in JSF controls, and controls from other third-party libraries. We recommend JBoss RichFaces, and Apache MyFaces Trinidad tag libraries for use with Seam. We do not recommend the use of the Tomahawk tag library.

To use these tags, define the "s" namespace in your page as follows (facelets only):

<html xmlns=""

The ui example demonstrates the use of a number of these tags.


Assigns an entity converter to the current component. This is useful for radio button and dropdown controls.

The converter works with any managed entity - either simple or composite. The converter should be able to find the items declared in the JSF controls on form submission, otherwise you will receive a validation error.




You must use Seam managed transactions (see Section 9.2, “Seam managed transactions”) with <s:convertEntity />.

If your Managed Persistence Context isn't called entityManager, then you need to set it in components.xml:

<components xmlns=""
   <ui:jpa-entity-loader entity-manager="#{em}" />

If you are using a Managed Hibernate Session then you need to set it in components.xml:

<components xmlns=""
   <ui:hibernate-entity-loader />

If your Managed Hibernate Session isn't called session, then you need to set it in components.xml:

<components xmlns=""
   <ui:hibernate-entity-loader session="#{hibernateSession}" />

If you want to use more than one entity manager with the entity converter, you can create a copy of the entity converter for each entity manager in components.xml - note how the entity converter delegates to the entity loader to perform persistence operations:

<components xmlns=""
   <ui:entity-converter name="standardEntityConverter" entity-loader="#{standardEntityLoader}" />
   <ui:jpa-entity-loader name="standardEntityLoader" entity-manager="#{standardEntityManager}" />
   <ui:entity-converter name="restrictedEntityConverter" entity-loader="#{restrictedEntityLoader}" />
   <ui:jpa-entity-loader name="restrictedEntityLoader" entity-manager="#{restrictedEntityManager}" />
<h:selectOneMenu value="#{person.continent}">
   <s:selectItems value="#{continents.resultList}" var="continent" 
                  label="#{}" />
    <f:converter converterId="standardEntityConverter" />


<h:selectOneMenu value="#{person.continent}" required="true">
   <s:selectItems value="#{continents.resultList}" var="continent" 
                  noSelectionLabel="Please Select..."/>
   <s:convertEntity />


Renders a file upload control. This control must be used within a form with an encoding type of multipart/form-data, i.e:

<h:form enctype="multipart/form-data">

For multipart requests, the Seam Multipart servlet filter must also be configured in web.xml:

  <filter-name>Seam Filter</filter-name>

  <filter-name>Seam Filter</filter-name>


The following configuration options for multipart requests may be configured in components.xml:

Here's an example:

<component class="org.jboss.seam.web.MultipartFilter">
  <property name="createTempFiles">true</property>
  <property name="maxRequestSize">1000000</property>



<s:fileUpload id="picture" data="#{register.picture}" 
              contentType="#{register.pictureContentType}" />


An extended <h:graphicImage> that allows the image to be created in a Seam Component; further transforms can be applied to the image.

All attributes for <h:graphicImage> are supported, as well as:



To apply a transform to the image, you would nest a tag specifying the transform to apply. Seam currently supports these transforms:

It's easy to create your own transform - create a UIComponent which implements org.jboss.seam.ui.graphicImage.ImageTransform. Inside the applyTransform()method use image.getBufferedImage() to get the original image and image.setBufferedImage() to set your transformed image. Transforms are applied in the order specified in the view.


<s:graphicImage rendered="#{auction.image ne null}"
  <s:transformImageSize width="200" maintainRatio="true"/>

Seam also provides annotations to allow you to use Seam components as JSF converters and validators:


public class ItemConverter implements Converter {
   public Object getAsObject(FacesContext context, UIComponent cmp, String value) {
      EntityManager entityManager = (EntityManager) Component.getInstance("entityManager");
      // Do the conversion
   public String getAsString(FacesContext context, UIComponent cmp, Object value) {
      // Do the conversion

<h:inputText value="#{shop.item}" converter="itemConverter" />

Registers the Seam component as a JSF converter. Shown here is a converter which is able to access the JPA EntityManager inside a JTA transaction, when converting the value back to it's object representation.


public class ItemValidator implements javax.faces.validator.Validator {
   public void validate(FacesContext context, UIComponent cmp, Object value)
         throws ValidatorException {
      ItemController ItemController = (ItemController) Component.getInstance("itemController");
      boolean valid = itemController.validate(value);
      if (!valid) {
         throw ValidatorException("Invalid value " + value);

<h:inputText value="#{shop.item}" validator="itemValidator" />

Registers the Seam component as a JSF validator. Shown here is a validator which injects another Seam component; the injected component is used to validate the value.