SeamFramework.orgCommunity Documentation

Chapter 33. Seam JSF controls

33.1. Tags
33.1.1. Navigation Controls
33.1.2. Converters and Validators
33.1.3. Formatting
33.1.4. Seam Text
33.1.5. Form support
33.1.6. Other
33.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, ICEsoft ICEfaces 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 />


"Decorate" a JSF input field when validation fails or when required="true" is set.


#{invalid} and #{required} are available inside s:decorate; #{required} evaluates to true if you have set the input component being decorated as required, and #{invalid} evaluates to true if a validation error occurs.


<s:decorate template="edit.xhtml">
   <ui:define name="label">Country:</ui:define>
      <h:inputText value="#{}" required="true"/>

<ui:composition xmlns=""
      <s:label styleClass="#{invalid?'error':''}">
         <ui:insert name="label"/>
         <s:span styleClass="required" rendered="#{required}">*</s:span>
      <span class="#{invalid?'error':''}">
      <s:message styleClass="error"/>     


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.