OCPSoft.com - Simple SolutionsCommunity Documentation
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 the PrettyFaces JAR file 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.
As of PrettyFaces 3.3.0, no additional JAR files for are required for Non-Maven users; installation is just a single download and install.
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.)
Example 2.1. /WEB-INF/web.xml (Ignore if using Servlet 3.0)
<filter> <filter-name>Pretty Filter</filter-name> <filter-class>com.ocpsoft.pretty.PrettyFilter</filter-class> </filter> <filter-mapping> <filter-name>Pretty Filter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> <dispatcher>ERROR</dispatcher> </filter-mapping>
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.
Example 2.2. /WEB-INF/pretty-config.xml (You will need to customize this)
<pretty-config xmlns="http://ocpsoft.com/prettyfaces/3.3.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ocpsoft.com/prettyfaces/3.3.0
http://ocpsoft.com/xml/ns/prettyfaces/ocpsoft-pretty-faces-3.3.0.xsd">
<!-- Begin Example RewriteRules
// These are custom rewrite-rules, and are probably not necessary for your application.
<rewrite match="^/old-url/(\w+)/$" substitute="/new_url/$1/" redirect="301" />
-->
<!-- Begin UrlMappings
// These are examples of URL mappings, and should be customized for your application.
<url-mapping id="home">
<pattern value="/" />
<view-id value="/faces/index.jsf" />
</url-mapping>
<url-mapping id="store">
<pattern value="/store/" />
<view-id value="/faces/shop/store.jsf" />
</url-mapping>
<url-mapping id="viewCategory">
<pattern value="/store/#{ cat : bean.category }/" />
<view-id value="/faces/shop/store.jsf" />
</url-mapping>
<url-mapping id="viewItem">
<pattern value="/store/#{ cat : bean.category }/#{ iid : bean.itemId }/" />
<view-id value="/faces/shop/item.jsf" />
<action>#{bean.loadItem}</action>
</url-mapping>
-->
</pretty-config>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.
During the development of your application you will typically have to make changes to your
pretty-config.xml very often. As server restarts take a lot of time and decrease productivity,
PrettyFaces is capable of reloading its configuration on a regular basis. As the configuration reloading
may be a time consuming process for large applications, PrettyFaces reloads its configuration only
if the application is executed in development mode.
To enable the development mode, add the following context parameter to your web.xml:
<context-param> <param-name>com.ocpsoft.pretty.DEVELOPMENT</param-name> <param-value>true</param-value> </context-param>
If your are using the JSF 2.0 version of PrettyFaces, you typically won't have to explicitly enable
the development mode. In this case the development mode is automatically enabled for all project
stages except for Production.