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 JSF Libraries (please refer to
Creating and Updating JSF Libraries).
The following image demonstrates one approach to setting up required libraries - relevant JSF libraries and their typical Java libraries ("JARs") are outlined in red, JSF Library names and JAR filesystem locations are arbitrary:
Example of JSF Libraries
NOTE: The image above shows libraries typically required for a recent version of Trinidad for JSF 1.2 - other versions may have different requirements. Please consult online resources at the
Apache MyFaces Trinidad website for complete and current information.
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>
