OCPSoft.com - Simple SolutionsCommunity Documentation

Chapter 2. Get Started

2.1. Get PrettyFaces
2.2. Configure PrettyFaces in web.xml
2.3. Create /WEB-INF/pretty-config.xml

It should not be difficult to install PrettyFaces into any new or existing Servlet-based application. Follow the next few steps and you should have a working configuration in only a few minutes.

This step is pretty straight-forward, right? Copy necessary JAR files into your /WEB-INF/lib directory, or include a Maven dependency in your pom.xml (recommended):

Non-Maven users may download JAR files manually from one of the following repositories: (Central, OcpSoft). Be sure to select the correct package for your version of JSF.

Note

Non-Maven Users must also include the following required JAR dependencies (downloaded separately) in addition to the PrettyFaces JAR file:

List of Maven Dependencies:

<!-- for JSF 2.x -->
<dependency>
   <groupId>com.ocpsoft</groupId>
   <artifactId>prettyfaces-jsf2</artifactId>
   <version>${latest.prettyfaces.version}</version>
</dependency>

<!-- for JSF 1.2.x -->
<dependency>
   <groupId>com.ocpsoft</groupId>
   <artifactId>prettyfaces-jsf12</artifactId>
   <version>${latest.prettyfaces.version}</version>
</dependency>

<!-- for JSF 1.1.x (UNSUPPORTED) -->
<dependency>
   <groupId>com.ocpsoft</groupId>
   <artifactId>prettyfaces-jsf11</artifactId>
   <version>${latest.prettyfaces.version}</version>
</dependency>

If you are using a Servlet 3.0 compliant container, you may skip this step because PrettyFaces will automatically register the required Servlet Filter; otherwise, make sure PrettyFilter is the first filter in your web.xml file. (The dispatcher elements are required to ensure PrettyFaces intercepts both internal and external requests.)


This is where you'll tell PrettyFaces what to do, which URLs to rewrite. Each URL-mapping contained in the configuration must specify a pattern and a viewId. The pattern specifies which inbound URL to match, and the viewId specifies the location that URL should resolve -be redirected- to.


Tip

In JAR files, pretty-config.xml may also be placed in /META-INF/pretty-config.xml - additionally, comma-separated configuration file locations may be specified in web.xml, using the servlet context-param configuration API:

<context-param>
	<param-name>com.ocpsoft.pretty.CONFIG_FILES</param-name>
	<param-value>/WEB-INF/custom-mappings.xml,/META-INF/another-config.xml</param-value>
</context-param>

Congratulations! That's all you should have to do in order to use PrettyFaces. The rest of this reference guide covers detailed configuration options, framework integration with JavaServer Faces, and special use-cases.