Apache MyFaces Trinidad - Initial Setup Guide

Overview

This guide intends to aid with the initial setup of a dynamic web application to make use of the Apache MyFaces Trinidad ("Trinidad") JSF library. While the goal is that this serves as sufficient information to guide the user through initial setup, the Trinidad website should always be considered as the source of complete and current information. This guide is intended for setup of Trinidad for use with the Eclipse Web Tools Platform ("WTP") more than as a general Trinidad setup guide (although the core concepts may not be specific to WTP).

Dynamic Web Project Setup

JSF Library Configuration

As with all frameworks, Trinidad requires certain libraries to be on the classpath. Some libraries may be provided by the server runtime (for example, a JEE5 server runtime will likely provide a JSF 1.2 implementation and JSTL 1.2). When required libraries are not provided by the server runtime, it is recommended that they be added as one or more user Libraries (please refer to Creating and Updating JSF Libraries).

Dynamic Web Project Configuration

When creating a Dynamic Web Project, specify the use of the JavaServer Faces (v1.1 or v1.2, depending on requirements) Project "Configuration", as shown below:

JavaServer Faces v1.2 Project

Proceed through the wizard until reaching the JSF Capabilities page. On this page, select the required JSF Libraries as previously created, as shown below:

JSF Capabilities

NOTE: If JSF Libraries were created with different names than shown above, the available library names may differ.

Complete the wizard to create the Dynamic Web Project.

Web Application Descriptor Additions

Some additions to the web application's descriptor (.../WEB-INF/web.xml) are required, and some additions are optional.

NOTE: Please consult online resources at the Apache MyFaces Trinidad website for complete and current information.

Required Additions

The following additions need to be made to the web application's descriptor to configure Trinidad's resource servlet (which serves stylesheets, scripts, and images at runtime):

  <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 following additions need to be made to the web application's descriptor to configure Trinidad's filter:

  <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>

NOTE: The filter-mapping shown above assumes that the standard JSF servlet's servlet-name is specified as "faces" - this may differ depending on user setup, and so should be specified appropriately.

Optional Additions

The following additions to the web application's descriptor are optional, depending on your specific application's requirements:

  <context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>client</param-value>
  </context-param>

  <context-param>
    <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
    <param-value>.jspx</param-value>
  </context-param>

  <context-param>
    <param-name>org.apache.myfaces.trinidad.USE_APPLICATION_VIEW_CACHE</param-name>
    <param-value>false</param-value>
  </context-param>

  <context-param>
    <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
    <param-value>false</param-value>
  </context-param>

  <context-param>
    <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
    <param-value>session</param-value>
  </context-param>

  <context-param>
    <param-name>org.apache.myfaces.trinidad.resource.DEBUG</param-name>
    <param-value>false</param-value>
  </context-param>

NOTE: Some of these optional additions are Trinidad-specific, and some are not.

JSF Application Configuration Resource Additions

An addition to the JSF application configuration resource (typically .../WEB-INF/faces-config.xml) is required.

NOTE: Please consult online resources at the Apache MyFaces Trinidad website for complete and current information.

Required Addition

The following addition needs to be made to the JSF application configuration resource to configure Trinidad's core RenderKit:

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