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:
- It has a large number of components. There is a component for nearly everything, in Trinidad.
- It has many “all-in-one” components. Some of the Trinidad components render multiple elements. With some other component sets, we need several components to get the same effect.
- It has advanced skinning possibilities.
- It has a lot of advanced options for displaying tabular and hierarchical data.
- It has a chart component, making it fairly easy to display numeric data in a visual way.
- It has a dialog framework, making it easy to create pop-up dialogs.
- “Partial page rendering”, client-side validation and conversion, and other AJAX functionality are embedded in most components and is easy to add where needed. (This is especially important for JSF 1.2 users.)
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>
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:
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.