MyFaces Trinidad

Trinidad is a very extensive set of JSF components. It was developed by Oracle under the name ADF Faces. When Oracle donated this component set to the ADF Faces project, it was renamed to Trinidad. As with the Core project, there are three versions of Trinidad for each version of the JSF standard. Trinidad releases numbered 1.0.x are compatible with JSF 1.1, and releases numbered 1.2.x are compatible with JSF 1.2. Releases for JSF 2.0 are numbered 2.0.x. At this moment, only beta releases are available for JSF 2.0.

Some of the most important characteristics of Trinidad are:

Getting started with Trinidad

As with other component libraries, the first thing to do in order to get started with Trinidad is to download it. Note that Trinidad comes in three versions—a JSF 1.1 version, a JSF 1.2 and a JSF 2.0 version. The JSF version is reflected in the version number of Trinidad. This means that versions 1.0.10 and 1.2.10 are basically the same versions. The only difference is that 1.0.10 is the version for JSF 1.1, whereas 1.2.10 is the version for JSF 1.2. The downloaded archive contains, among other things, two JARs that we’ll have to add to our project—trinidad-api-x.y.z.jar and trinidad-impl-x.y.z.jar. Of course, we don’t have to add the JARs manually if we use Maven.

Configuring the web.xml file

Before we can use Trinidad, we’ll have to add some settings to our web.xml file. First, we have to add a filter configuration for Trinidad, which should look like this:

    <filter>
        <filter-name>trinidad</filter-name>
        <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>trinidad</filter-name>
        <servlet-name>Faces Servlet</servlet-name>
    </filter-mapping>

Note that the filter is mapped to the standard Faces Servlet, which is named Faces Servlet in this example. This name might be different in your own project.

We also have to set up a resource Servlet for Trinidad:

    <servlet>
        <servlet-name>resources</servlet-name>
        <servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>resources</servlet-name>
        <url-pattern>/adf/*</url-pattern>
    </servlet-mapping>

The resource Servlet is mapped to the /adf/* URL. This is a remainder from the days before Oracle donated its ADF Faces components to the MyFaces project. The URL cannot be changed, as some parts of Trinidad expect to be able to access CSS and JavaScript files via this URL.

If you're using Trinidad 1.2 and you're using Facelets as view technology, one extra step has to be taken, in order to let Trinidad 1.2 play nice with Facelets. Just add the following context parameter setting to the web.xml file:

    <context-param>
        <param-name>org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER</param-name>
        <param-value>com.sun.facelets.FaceletViewHandler</param-value>
    </context-param>

This makes the Trinidad components aware of the fact that Facelets is being used instead of JSP as the view technology. Again, this only applies to Trinidad 1.2 when used with Facelets. In JSF 2.0 Facelets is the standard view technology, so no alternate view handler is necessary.

Configuring the faces-config.xml file

In the faces-config.xml file, we have to set the default render kit for Trinidad. This can be done with just a single element:

    <default-render-kit-id>org.apache.myfaces.trinidad.core</default-render-kit-id>

We also have to make sure that we do not set the Facelets view handler in the faces-config.xml file. If you ever get a java.lang.IllegalStateException stating "No RenderingContext" from the Trinidad renderer, then it is probably because the Facelets view handler is defined in the faces-config.xml file.

Configuring the trinidad-config.xml file

Trinidad also introduces another configuration file—trinidad-config.xml. As the name implies, this file can be used to adjust several Trinidad-specific settings. This file is optional, which means that we don’t have to create it if Trinidad’s default values are fine for our project. A basic trinidad-config.xml file looks like this:

<?xml version="1.0"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
    <debug-output>true</debug-output>
    <skin-family>minimal</skin-family>
</trinidad-config>

Setting debug-output to true will cause Trinidad to add some helpful comments to the generated pages, and format the XHTML nicely. Of course, this comes at the expense of performance, so you should disable this setting in production environments. The skin-family setting can be used to select an alternative skin for Trinidad.

Drafts/Site/Trinidad (last edited 2011-03-18 13:55:28 by BartKummel)