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