prettyfaces

SEO and Consistency:

Any business knows how important Search Engine Optimization can be for sales. PrettyFaces allows SEO-friendly URLs, and improved customer experience. Give your site a uniform, well understood feeling, from the address bar to the buy button.

Get Started, it’s easy! (3 steps)

1. Include PrettyFaces in your Project

You may either use Maven (recommended) to include PrettyFaces in your project, or you can download the distribution ZIP file directly.

<!-- for Jakarta EE 8, 9, 10+ -->
<dependency>
    <groupid>org.ocpsoft.rewrite</groupid>
    <artifactid>rewrite-servlet</artifactid>
    <version>{Version 8.x.x, 9.x.x, 10.x.x}</version>
</dependency>
<dependency>
    <groupid>org.ocpsoft.rewrite</groupid>
    <artifactid>rewrite-config-prettyfaces</artifactid>
    <version>{Version 8.x.x, 9.x.x, 10.x.x}</version>
</dependency>

<!-- for JSF 2.x -->
<dependency>
    <groupid>org.ocpsoft.rewrite</groupid>
    <artifactid>rewrite-servlet</artifactid>
    <version>3.5.2.Final</version>
</dependency>
<dependency>
    <groupid>org.ocpsoft.rewrite</groupid>
    <artifactid>rewrite-config-prettyfaces</artifactid>
    <version>3.5.2.Final</version>
</dependency>

(If you use an older version of JSF, you will want to use the legacy PrettyFaces JSF 1.x dependency instead →)

<!-- for JSF 1.2.x (yea, we know the version number is confusing. sorry!)--><br>
<dependency>
   <groupid>com.ocpsoft</groupid>
   <artifactid>prettyfaces-jsf12</artifactid>
   <version>3.3.3</version>
</dependency>

2. Create pretty-config.xml

This is where you will create URL mappings between external URL patterns and your internal view files, Servlets, and other resources. Be sure to replace the mapping below with a mapping that matches your application.

<pretty-config xmlns="http://ocpsoft.org/schema/rewrite-config-prettyfaces" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://ocpsoft.org/schema/rewrite-config-prettyfaces
                      http://ocpsoft.org/xml/ns/prettyfaces/rewrite-config-prettyfaces.xsd">
	<url-mapping id="login">
		<pattern value="/login" />
		<view-id value="/legacy/user/login.jsp" />
	</url-mapping>
</pretty-config>

Add mappings to your configuration

This part is all up to you! You’ll need to figure out which URLs in your application you want to “prettify” – so check out the [[PrettyFaces Docs|documentation]] for details on how to fully utilize the PrettyFaces URL-mapping system.

Additionally, be sure to check out the Rewrite examples or reference manual to learn more about [[Rewrite]], and the powerful options it offers beyond the PrettyFaces configuration module.

<url-mapping id="view-user">
	<pattern value="/user/#{username}" />
	<view-id value="/user/view.xhtml" />
</url-mapping>

3. Run your application!

You should now be ready to go! PrettyFaces is installed and your first URL-mapping has been created. If everything has been done correctly, you should see PrettyFaces log a message confirming that setup was successful.

INFO  [org.ocpsoft.rewrite.servlet.RewriteFilter] RewriteFilter starting up...
...
INFO  [org.ocpsoft.rewrite.servlet.RewriteFilter] Loaded [] org.ocpsoft.rewrite.config.ConfigurationProvider [org.ocpsoft.rewrite.prettyfaces.PrettyFacesRewriteConfigurationProvider]
INFO  [org.ocpsoft.rewrite.servlet.RewriteFilter] RewriteFilter initialized.

Documentation (Need help?)

Ask a question in the forums, view the documentation, FAQ, or get the source!

Features

1. URL Rewriting — Replace ugly URLs: “/faces/page.jsf” with pretty, SEO-friendly, human URLS: “/optimized/page/”; The client browser never sees your original URLs, even in the source-HTML
2. Dynamic view IDs — Now with dynamic view ID mapping for URLs (through El method expressions,) you can show different views based on run-time conditions, effectively de-coupling the URL from the JSF view.
3. Page-load actions — Call one or more action-methods, at one or more phases, before rendering a view.
4. Managed parameter parsing — HTTP parameters parsed from URLs are stored in managed beans, simply get a reference to your parameter bean for easy access from other Java classes.
5. Navigation by ID — Define your page IDs in one place, reference them easily in action-methods and components, using standard JSF navigation techniques.
6. Integrated validation — For URL and query-parameters, able to re-use existing JSF validator objects.
7. Easy to configure — Requires absolutely minimal configuration; may be enabled using XML or annotations.

What makes PrettyFaces different:

View a slideshare presentation on why URL Rewriting is important, or a brief overview of the problems PrettyFaces solves.

FAQ

1. Q. Can I use PrettyFaces to handle URL-rewriting for other resources on my server as well?

   A. Yes. PrettyFaces still requires a configured JSF instance to function, but it can be used to map a URL to any resource in the Servlet Container – without invoking FacesServlet. Values will be injected into JSF beans as usual, but PrettyFaces Action methods will not trigger (since no JSF lifecycle executes for non-Faces requests.)

   For example:
   

   pretty-config.xml

   <pretty-config xmlns="http://ocpsoft.org/schema/rewrite-config-prettyfaces" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://ocpsoft.org/schema/rewrite-config-prettyfaces
                         http://ocpsoft.org/xml/ns/prettyfaces/rewrite-config-prettyfaces.xsd">
   	<url-mapping id="login">
   		<pattern value="/login" />
   		<view-id value="/legacy/user/login.jsp" /> <!-- Non JSF View Id -->
   	</url-mapping>
   	<url-mapping id="register">
   		<pattern value="/register" />
   		<view-id value="/faces/user/register.jsf" /> <!-- JSF View Id -->
   	</url-mapping>
   </pretty-config>

2. Q. Why do my Tomahawk / MyFaces components, or other 3rd party addons, break when I use PrettyFaces?

   A. Since PrettyFaces intercepts mapped HttpRequests then forwards those requests to JSF, it is necessary to enable any additional filters between PrettyFaces and JSF to listen to Servlet Forwards. This is done in the web.xml deployment descriptor by adding the following dispatcher elements to any needed Filters:

   For example:
   

   web.xml

   <filter-mapping>
   	<filter-name>springSecurityFilterChain</filter-name>
   	<url-pattern>/*</url-pattern>
   	<dispatcher>FORWARD</dispatcher>
   	<dispatcher>REQUEST</dispatcher>
   </filter-mapping>

3. Q. Why, when using MyFaces, am I getting a NullPointerException when I try to use normal faces-navigation?

   A. Some MyFaces versions do not completely comply with the JSF specification, thus the ViewRoot is null when the request is processed. There is a patch/workaround, which can be added to fix this issue. You must add this ViewHandler to your faces-config.xml.

4. Q. Can I configure PrettyFaces via Annotations?

   A. Yes! Thanks to Christian Kapolteth, PrettyFaces has Annotations support as of version 3.0.2-SNAPSHOT

5. Q. How do I enable logging, so that I can tell what the heck is really going on?

   A. Create or update your log4j.properties file with the following values:
   

   log4j.properties

   ### direct log messages to stdout ###>
   log4j.appender.stdout=org.apache.log4j.ConsoleAppender
   log4j.appender.stdout.Target=System.out
   log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
   log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n
   log4j.rootLogger=warn, stdout
   ### Log for OCPsoft
   log4j.logger.com.ocpsoft=info

6. Q. Can I map and process URLs that span a dynamic number of ‘/’ characters?

   A. Yes, please read section 3.4 of the docs.

7. Q. How do I save FacesMessage objects after performing a redirect or pretty:redirect?

   A. You need to configure the optional MultiPageMessagesSupport PhaseListener (or something like it)

   faces-config.xml

   <br>
   <!--?xml version='1.0' encoding='UTF-8'?--><br>
   <faces-config xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://java.sun.com/xml/ns/javaee 
   	http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd" version="1.2">
   	<lifecycle>
   		<phase-listener>
   			com.ocpsoft.pretty.application.MultiPageMessagesSupport
   		</phase-listener>
   	</lifecycle>
   </faces-config>

   See this article for a full explanation of how this works.

8. Q. Does PrettyFaces work on IBM’s WebSphere?

   A. Yes, but websphere requires a custom setting in order to behave like a sane server.
   

Support us – Donate

We welcome donations to continue providing a home to the OCPsoft open-source projects. Or, if you like this project, you can become powered by PrettyFaces. All donations go directly to offset our web hosting costs.