Trinidad comes with build-in support for Facelets, which is a cool view layer technology. The trinidad-impl.jar contains the Facelets taglib.xml file, so you don't need to create such a file.

Configuration

In order to use Facelets with Trinidad you need to edit your web.xml file.

web.xml

Add the FaceletViewHandler and the DEFAULT_SUFFIX param to your web.xml:

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

<!-- Use documents saved as *.xhtml for Facelets -->
<context-param>
  <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
  <param-value>.xhtml</param-value>
</context-param>

Alternatively, if you want to use both JSPs and Facelets in the same project, use facelets.VIEW_MAPPINGS:

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

<!-- Use documents saved as *.xhtml for Facelets -->
  <context-param>
    <param-name>facelets.VIEW_MAPPINGS</param-name>
    <param-value>*.xhtml</param-value>
  </context-param>     

A complete example file is listed below.

faces-config.xml

You don't need to configure any specials for using Facelets with Trinidad. Do not add the FaceletsViewHandler here! But be sure you have the Trinidad RenderKit ID in this file, like:

<application>
  <!-- Use the Trinidad RenderKit -->
  <default-render-kit-id>
    org.apache.myfaces.trinidad.core
  </default-render-kit-id>
</application>

XHTML file

Facelets is easy a small simple Facelets page looks like:

<tr:document
   xmlns:ui="http://java.sun.com/jsf/facelets"
   xmlns:h="http://java.sun.com/jsf/html"
   xmlns:f="http://java.sun.com/jsf/core"
   xmlns:tr="http://myfaces.apache.org/trinidad"
   title="Facelets">

  <tr:form>
      <tr:inputText label="Your name" id="input1" value="#{backing.name}" />
      <tr:commandButton id="button1" text="press me" action="#{backing.send}" />
  </tr:form>

</tr:document>

Sample web.xml file

<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<!--
  Copyright 2006 The Apache Software Foundation.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">
         
  <!-- Trinidad has its own ViewHandler, which is a "decorating"
       view handler - for example, it needs to wrap methods like renderView()
       to perform some extra pre- and post-handling.  Facelets, on the other
       hand, is more of a true ViewHandler - it actually implements
       renderView() (yeah, it decorates too, but forget about that
       for a second).  As a result, the world is a better place if
       the Trinidad ViewHandler runs around the Facelets ViewHandler.
       But since Facelets is registered in WEB-INF/faces-config.xml,
       and Trinidad's is registered from META-INF/faces-config.xml in its
       JAR, exactly the opposite happens as per the JSF spec.

       Hence, the following config parameter, which Trinidad
       exposes to allow pushing a ViewHandler inside
       of ours.  FWIW, you retain the entire delegation stack - 
       just flipped around a bit - so that Facelets still decorates
       the standard ViewHandler, and therefore you've still got
       JSP support.
  -->
  <context-param>
    <param-name>org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER</param-name>
    <param-value>com.sun.facelets.FaceletViewHandler</param-value>
  </context-param>

  <context-param>
    <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
    <param-value>.xhtml</param-value>
  </context-param>
  
  <!-- Use client-side state saving.  In Trinidad, it is an
       optimized, token-based mechanism that is almost always a
       better choice than the standard JSF server-side state saving. -->
  <context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>client</param-value>
    <!--param-value>server</param-value-->
  </context-param>

  <!-- Trinidad by default uses an optimized client-side state saving
       mechanism. To disable that, uncomment the following -->
  <!--context-param>
    <param-name>org.apache.myfaces.trinidad.CLIENT_STATE_METHOD</param-name>
    <param-value>all</param-value>
  </context-param-->

  <!-- Trinidad also supports an optimized strategy for caching some
   view state at an application level, which significantly improves
   scalability.  However, it makes it harder to develop (updates to
   pages will not be noticed until the server is restarted), and in
   some rare cases cannot be used for some pages (see Trinidad
   documentation for more information) -->
  <context-param>
    <param-name>org.apache.myfaces.trinidad.USE_APPLICATION_VIEW_CACHE</param-name>
    <param-value>false</param-value>
  </context-param>

  <!-- If this parameter is enabled, Trinidad will automatically
       check the modification date of your JSPs, and discard saved
       state when they change;  this makes development easier,
       but adds overhead that should be avoided when your application
       is deployed -->
  <context-param>
    <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
    <param-value>true</param-value>
  </context-param>

  <!-- Enables Change Persistence at a session scope.  By default,
       Change Persistence is entirely disabled. The ChangeManager is
       an API, which can persist component modifications (like,
       is a showDetail or tree expanded or collapsed). For providing
       a custom Change Persistence implementation inherit from the 
       Trinidad API's ChangeManager class. As the value you have 
       to use the fullqualified class name. -->
  <context-param>
    <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
    <param-value>session</param-value>
  </context-param>

  <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-name>
  </filter-mapping>
  
  <!-- Faces Servlet -->
  <servlet>
    <servlet-name>faces</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
  </servlet>
  
  <!-- resource loader servlet -->
  <servlet>
    <servlet-name>resources</servlet-name>
    <servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
  </servlet>

  <!-- Faces Servlet Mappings -->
  <servlet-mapping>
    <servlet-name>faces</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>
  
  <servlet-mapping>
    <servlet-name>resources</servlet-name>
    <url-pattern>/adf/*</url-pattern>
  </servlet-mapping>

</web-app>

Using Trinidad PPR (Partial Page Rendering) with Facelets

There is an issue in the id generation for components when a PPR is executed. The symptom is that a click on an command does not execute the desired action but only reloads the whole page. Any subsequent click on any command succeeds.

To work around this issue manually set the id's for at least all commands on the affected pages.

This is fixed in Facelets version 1.1.14

Please notice that using the autoSubmit feature in some Trinidad components issues a PPR. Consider using something like onchange="submit()" to reload the whole page.

XHTML comments and Facelets

Once you are using Facelets you are perhaps interested in putting some comments to your XHTML template like:

<tr:navigationPane hint="bar" >
  <tr:commandNavigationItem immediate="true" text="...."  action="....."  />
  <!-- Start comment  -->
  <!-- End comment -->
  <tr:commandNavigationItem immediate="true" text="...."  action="....." />
  <tr:commandNavigationItem immediate="true" text="...." action="....." />
</tr:navigationPane>

Not every component likes this, because the comments are interpreted as regular components and not every component likes every other component to be its child:

SEVERE: Warning: illegal component hierarchy detected, expected UIXCommand but
found another type of component instead.
java.lang.ClassCastException: com.sun.facelets.tag.ui.ComponentRef

To handle those comments without any side effect, add the following to your project's web.xml file:

<context-param>
  <param-name>facelets.SKIP_COMMENTS</param-name>
  <param-value>true</param-value>
</context-param>