PrettyFaces Reference Guide

While compatible with any Servlet 2.5+ container, some features are only available in JavaServer Faces.

Sections describing these features are marked with a '*'. This means that the feature either requires JSF, or requires an environment that has configured JSF in order to function; otherwise, those marked features will not be available.

PrettyFaces is an OpenSource extension for Servlet, Java EE, and JSF, which enables creation of bookmarkable, REST-ful, "pretty" URLs. PrettyFaces solves several problems elegantly, such as: custom URL-rewriting, page-load actions, seamless integration with JSF navigation and links, dynamic view-id assignment, managed parameter parsing, and configuration-free compatibility with other JSF frameworks.

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.

What is sometimes neglected, even when building web-sites that aren't for external customers, is the consistency of the URL displayed to users in the browser address bar. Keeping the URL tidy can make a big difference in usability, providing that smooth web-browsing experience.

http://ocpsoft.com/index.jsf?post=docs&category=prettyfaces

<url-mapping>
   <pattern value="/#{post}/#{category}" />
   <view-id>/index.jsf</view-id>
</url-mapping>

http://ocpsoft.com/docs/prettyfaces/

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.

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

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

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

The URL mapping element is the core configuration element for PrettyFaces most applications. Let's consider, for instance, that we are building a web-store and we want our users to access the store at the URL /store/ - we only need the most basic features of the URL-mapping to achieve this.

<url-mapping id="store"> 
   <pattern value="/store/" /> 
   <view-id value="/faces/shop/store.jsf" />
</url-mapping>

With these two simple lines of configuration, the user sees: pattern="/store/" in the browser URL and in the output HTML, but the server is actually rendering the resource: /faces/shop/store.jsf (the actual location of the page on the server.)

Ignore the id="store" attribute for now, we'll cover that under navigation. Which is useful when redirecting a user between different pages in your application.

Suppose we want to create a URL mapping that allows users to access items in a specific category of a web-store, such as: /store/category/. In other words, we want to take a piece of the URL string itself - for example: /store/[category]/ and use that value: [category] in our application's logic.

This is commonly known as creating a REST-ful URL, but here we'll use the term "path-parameter" to represent each individual data element created in our URL path.

<pattern value="/#{ name }/" />

<url-mapping id="viewCategory">
  <pattern value="/store/#{ cat }/" />
  <view-id value="/faces/shop/store.jsf" /> 
</url-mapping>

Here we've used PrettyFaces path-parameter syntax to capture values stored in part of inbound URLs that match our pattern. Take, for instance, the following URL:

/store/shoes/

Part of this URL will be matched by the path-parameter expression: '#{ cat }', making its value, 'shoes', available in the application logic, the rest of the URL will be matched against the pattern, but ignored.

<pattern value="/store/#{ cat }/" />

The application can gain access to these path-parameters in a few ways, via request parameter naming, or EL bean injection; both techniques will be covered below.

String category = request.getParameter("cat");

<pattern value="/store/#{ bean.category }/" />

@Named("bean")
@RequestScoped
public class CategoryBean {
	private String category;
	
	/* Getters & Setters */
}

<pattern value="/store/#{ cat : bean.category }/" />

<url-mapping id="archives">
  <pattern value="/#{ /\\d{4}/ year }/#{ /\\d{2}/ month }/" />
  <view-id value="/faces/blog/archives.jsf" /> 
</url-mapping>

/(\\d{4})/(\\d{2})/

<url-mapping id="viewAuthorPost">
  <pattern value="/#{ /[a-z]+/ blogger }/#{ /\\d+/ postId }/" />
  <view-id value="/faces/blog/viewPost.jsf"/> 
</url-mapping>

/([a-z]+)/(\\d+)/

<url-mapping id="viewCategory" onPostback="false">
  <pattern value="/store/#{ cat }/" />
  <view-id value="/faces/shop/store.jsf"/> 
</url-mapping>

Most people are already familiar with URL query-parameters. They come in key=value pairs, and begin where the '?' character is found in a URL. For example:

http://example.com/path?query=data

Here, 'query' is the name of the parameter, and 'data' is the value of the parameter; order of parameters does not matter, and if duplicates parameter names are encountered, an array of multiple values will be stored for that parameter.

While query-parameters are automatically stored in the HttpServletRequest parameter map, it may sometimes be convenient to also inject those values directly into JSF managed beans.

<query-param name="language"> #{bean.language} </query-param>

In this case, we must have a managed bean defined in our application; these beans can be registered either in JSF, Spring, Google Guice, or as shown here using CDI/Weld. Based on the configuration in this particular example, the bean must be named "bean", and must have an accessible field named "language".

<url-mapping id="store"> 
   <pattern value="/store/" /> 
   <view-id value="/faces/shop/store.jsf" />
   <query-param name="language"> #{bean.language} </query-param>
</url-mapping>

Any value matched by the query-parameter will be injected directly into the bean.

@Named("bean")
@RequestScoped
public class LanguageBean {
	private String language;
	
	/* Getters + Setters */
}

Please note that PrettyFaces will automatically use the JSF converter registered for the type of the referenced bean property to convert the query parameter. This means that PrettyFaces supports all JSF standard converters and converters that have been manually registered to be used for a specific type using the converter-for-class element in the faces-config.xml (or the forClass attribute of the @FacesConverter annotation).

<query-param name="language" decode="false"> #{bean.language} </query-param>

In some situations you might want that PrettyFaces doesn't inject the value of a query parameter on JSF postbacks. A typical usecase for this would be a query parameter that is used to initially populate a bean property holding the value bound to an input component. In this case you will want the query parameter value to be injected only on the initial GET request but not on postbacks, because the postback will contain the submitted value of the input component.

You can use the onPostback attribute to tell PrettyFaces whether you want the query parameter to be injected on postbacks. Please note that the default value of the attribute is true.

<query-param name="query" onPostback="false">#{searchBean.query}</query-param>

Frequently, you may find that several - or all - of your mappings share a common base-URL. It is on these occasions when you should consider using a parent URL-mapping by using the parentId attribute.

<url-mapping parentId="store" id="category"> ... </url-mapping>

Notice that the parentId attribute must refer to a mappingId of another URL-mapping. See examples below:

<url-mapping id="store"> 
   <pattern value="/store/" /> 
   <~-- Result: /store/ -->
   <view-id value="/faces/shop/store.jsf" />
</url-mapping>

<url-mapping parentId="store" id="category"> 
   <pattern value="/#{category}" /> 
   <~-- Result: /store/#{category} -->
   <view-id value="/faces/shop/category.jsf" /> 
</url-mapping>

<url-mapping parentId="category" id="item"> 
   <pattern value="/#{item}" /> 
   <~-- Result: /store/#{category}/#{item} -->
   <view-id value="/faces/shop/item.jsf" /> 
</url-mapping>

<url-mapping parentId="category" id="sales"> 
   <pattern value="/sales" /> 
   <~-- Result: /store/#{category}/sales -->
   <view-id value="/faces/shop/sales.jsf" /> 
</url-mapping>

At this time, only the pattern and path-parameter validators will be inherited by child mappings; however, this may be enhanced in future versions.

Dynamic view-IDs (referred to as DynaView) allow us to determine (at the time the page is requested) the page our users should see for a given URL-mapping pattern.

<url-mapping id="home">
	<pattern value="/home/" />
	<view-id value="#{bean.getViewPath}" />
</url-mapping>
		

Notice that we've used an EL method-expression where we would normally have specified a view-ID. PrettyFaces will invoke this method-expression, and use the result of the method as a final URL to be displayed by the server. In a sense, we're asking the system to figure out which page to display, and telling it that it can get the answer by calling our method:

@Named("bean")
@RequestScoped
public class HomeBean {
	
	@Inject CurrentUser user;
	
	public String getViewPath() {
		if ( user.isLoggedIn() )
		{
			return "/faces/home/home.jsf";
		}
		
		return "/faces/login.jsf";
	}
}

Here, our method #{bean.getViewPath} is going to check the current user's logged-in status, display the home page if he/she is logged in, or display the login page if they are not.

Most of the time, when creating bookmarkable URLs, it is not enough to simply display a page to the user; we also need to load data to be shown on that page - allowing for pages to appear completely stateless to the end-user. This would typically be difficult in JSF, but PrettyFaces has another option to satisfy this requirement that breaks the coupling typically associated with other solutions such as using @SessionScoped data beans to save data across pages, or passing values across views using: <f:setPropertyActionListener/>.

Consider, for a moment, that we have a web-store, and would like to map a URL to display one specific item in that store:

<url-mapping id="viewItem">
  <pattern value="/store/item/#{ iid : bean.itemId }/" />
  <view-id value="/faces/shop/item.jsf" /> 
  <action>#{bean.loadItem}</action>
</url-mapping>

@Named("bean")
@RequestScoped
public class CategoryBean {
	private String itemId;
	private String category;
	
	private Item item;
	
	@Inject StoreItems items;
	
	public String loadItem() {
		if ( itemId != null ) {
			this.item = items.findById(itemId);
			return null;
		}

		// Add a message here, "The item {..} could not be found."
		return "pretty:store";
	}
	
	/* Getters & Setters */
}

<url-mapping id="viewItem">
  <pattern value="/store/item/#{ iid : bean.itemId }/" />
  <view-id value="/faces/shop/item.jsf" /> 
  <action>#{bean.loadItem}</action>
</url-mapping>

@Named("bean")
@RequestScoped
public class CategoryBean {
	
	public String loadItem() {
		if ( itemId != null ) {
			this.item = items.findById(itemId);
			return null;
		}

		return "failure";
	}
}

<action phaseId="RENDER_RESPONSE">#{bean.loadItem}</action>

<action phaseId="PROCESS_VALIDATIONS">#{bean.loadItem}</action>

<action onPostback="false">#{bean.loadItem}</action>

The validation of path and query parameters is very important as they are directly modifiable by the user. Therefore PrettyFaces offers the possibility to attach validation code to each of your parameters.

<query-param name="language" validatorIds="languageValidator"> #{bean.language} </query-param>

<query-param name="language" validatorIds="languageValidator" onError="pretty:error"> #{bean.language} </query-param>

<query-param name="language" validator="#{languageBean.validateLanguage}"> #{bean.language} </query-param>

@Named("languageBean")
@RequestScoped
public class LanguageBean {

  public void validateLanguage(FacesContext context, UIComponent component, Object value) {

    for( String lang : Locale.getISOLanguages() ) {
      if( lang.equals( value.toString() ) ) {
        return;
      }
    }
    throw new ValidatorException( new FacesMessage("invalid.language") )

  }
  
}

<url-mapping id="viewCategory">
  <pattern value="/store/#{ cat }/">
    <validate index="0" validatorIds="categoryValidator" onError="pretty:error" />
  </pattern>
  <view-id value="/faces/shop/store.jsf" /> 
</url-mapping>

Recently PrettyFaces added support to configure URL mappings via annotations. This feature is primarily intended for people who don't want to maintain a separate XML configuration file for the mappings and instead prefer to declare them directly on the affected classes.

<context-param>
   <param-name>com.ocpsoft.pretty.BASE_PACKAGES</param-name>
   <param-value>com.example.myapp,com.ocpsoft</param-value>
</context-param>

<context-param>
   <param-name>com.ocpsoft.pretty.BASE_PACKAGES</param-name>
   <param-value>none</param-value>
</context-param>

<context-param>
   <param-name>com.ocpsoft.pretty.SCAN_LIB_DIRECTORY</param-name>
   <param-value>true</param-value>
</context-param>

@Named("bean")
@RequestScoped
@URLMapping(id = "store", pattern = "/store/", viewId = "/faces/shop/store.jsf")
public class StoreBean {
  /* your code */
}

@Named("bean")
@RequestScoped
@URLMapping(id = "categoryBean", pattern = "/store/#{ bean.category }/", viewId = "/faces/shop/store.jsf")
public class CategoryBean {
  
  private String category;
  
  /* Getters & Setters */ 
}

@Named("bean")
@RequestScoped
@URLMappings(mappings={
  @URLMapping(id = "categoryBean", pattern = "/store/#{ bean.category }/", viewId = "/faces/shop/store.jsf"),
  @URLMapping(id = "categoryBean2", pattern = "/shop/#{ bean.category }/", viewId = "/faces/shop/store.jsf")
})
public class CategoryBean {

  private String category;

  /* Getters & Setters */
}

@Named("bean")
@RequestScoped
@URLMapping(id = "viewItem", pattern = "/store/item/#{ bean.itemId }/", viewId = "/faces/shop/item.jsf")
public class CategoryBean {

  private String itemId;

  private Item item;

  @Inject 
  StoreItems items;

  @URLAction
  public String loadItem() {
    if ( itemId != null ) {
      this.item = items.findById(itemId);
      return null;
    }

    // Add a message here, "The item {..} could not be found."
    return "pretty:store";
  }

  /* Getters & Setters */
}

@URLAction(phaseId=PhaseId.RENDER_RESPONSE, onPostback=false)
public String loadItem() {
  // do something
}

@Named("bean")
@RequestScoped
@URLMapping(id = "viewItem", pattern = "/store/item/#{ bean.itemId }/", viewId = "/faces/shop/item.jsf")
public class CategoryBean {
  /* some code */
}

@Named("otherBean")
@RequestScoped
public class OtherBean {

  @URLAction(mappingId = "viewItem")
  public void myAction() {
    /* your code */
  }

}

@Named("bean")
@RequestScoped
public class LanguageBean {
 
  @URLQueryParameter("language")
  private String language;
  
  /* Getters + Setters */
}

@Named("bean")
@RequestScoped
public class LanguageBean {
 
  @URLQueryParameter("language")
  @URLValidator(validatorIds="com.example.LanguageValidator")
  private String language;
  
  /* Getters + Setters */
}

@Named("bean")
@RequestScoped
public class LanguageBean {
 
  @URLQueryParameter("language")
  @URLValidator(onError="pretty:error",
      validatorIds= { "com.example.LanguageValidator", "com.example.OtherValidator" })
  private String language;
  
  /* Getters + Setters */
}

@Named("bean")
@RequestScoped
@URLMapping(id = "viewItem", pattern = "/store/item/#{ bean.itemId }/", viewId = "/faces/shop/item.jsf",
  validation=@URLValidator(index=0, validatorIds="com.example.ItemIdValidator"))
public class CategoryBean {
  /* some code */
}

@URLBeanName("bean")
public class LanguageBean {
 
  @URLQueryParameter("language")
  private String language;
  
  /* Getters + Setters */
}

Typically when navigating in JSF, one must define navigation cases (in JSF 1.x) or return the path to a view (in JSF 2.x). PrettyFaces, however, lets us simply reference the URL-mapping ID in these scenarios. Since the URL-mapping pattern already contains the locations of all required values (path-parameter EL expressions), these values are extracted from managed beans and used in URL generation.

Simply return a URL-mapping ID from any JSF action-method just as you would when using an <h:commandLink action="..." />. This outcome string should be prefixed by "pretty:" followed e.g.: "pretty:store", where "store" is our URL-mapping ID.

<url-mapping id="viewItem">
  <pattern value="/store/item/#{ iid : bean.itemId }/" />
  <view-id value="/faces/shop/item.jsf" />
  <action>#{bean.loadItem}</action>
</url-mapping>

Now look at our action-method; notice that if the item is found, we return null, signaling that no navigation should occur, but if the item cannot be loaded, we return "pretty:store" which is a PrettyFaces navigation outcome; PrettyFaces will intercept this outcome string, and redirect the user to the URL-mapping identified by "store" in pretty-config.xml.

public String loadItem() {
	if(itemId != null) {
		this.item = items.findById(itemId);
		return null;
	}

	// Add a message here, "The item {..} could not be found."
	return "pretty:store";
}

If any action method (JSF action-method or PrettyFaces page-actions) returns a mapping-ID that specifies path-parameters in the pattern, PrettyFaces will automatically extract values from bean locations specified in the pattern. The client browser will be redirected to the URL built using these values injected back into the pattern. For example:

<pattern value="/store/#{ cat : bean.category }/" />

Let's assume for a moment that #{ bean.category } contains the value, "shoes". if we return "pretty:viewCategory" from our action method, where "viewCategory" is the id of a URL-mapping in pretty-config.xml, PrettyFaces will extract the current value from the bean #{ bean.category } and use that value to generate a new URL:

/store/shoes/

This means that we can control the generated URLs directly from Java code. Simply set the value of the bean field (the field used in the URL pattern) to control the outcome:

public String loadItem() {
	...
	// Add a message here, "The item {..} could not be found."
	this.setCategory("shoes");
	return "pretty:viewCategory";
}

It is also possible to navigate without needing a bean action method at all; this is done by referencing the URL-mapping ID in the command component directly. Similar to generating HTML links and URLs, for example:

<url-mapping id="viewItem">
	<pattern value="/store/#{ cat : bean.category }/#{ iid : bean.itemId }/" />
	<query-param name="language"> #{ bean.language } </query-param>
	<view-id value="/faces/shop/item.jsf" /> 
	<action>#{bean.loadItem}</action>
</url-mapping>

<h:commandLink action="pretty:home"> Go home. </h:commandLink> 

<h:commandLink action="pretty:"> Refresh this page. </h:commandLink> 

Often there you might find yourself somewhere in a custom Servlet, or in a situation where you do not have access to the Faces NavigationHandler. For these situations, PrettyFaces provides the PrettyURLBuilder, which can be used to generate the String representation of any URL-mapping; one need only have access to an HttpServletRequest object in order to get the current configuration, and the current HttpServletResponse in order to issue a redirect.

public class CustomRedirector 
{
	public void redirect(HttpServletRequest request, HttpServletResponse response, 
							String mappingId, Map<String, String[]>... params)
	{
		PrettyContext context = PrettyContext.getCurrentInstance(request);
		PrettyURLBuilder builder = new PrettyURLBuilder();
		
		URLMapping mapping = context.getConfig().getMappingById(mappingId);
		String targetURL = builder.build(mapping, params);
		
		targetURL = response.encodeRedirectURL(targetURL);
		response.sendRedirect(targetURL);
	}		
}

Many users add FacesMessages to the FacesContext in their action methods to display them on the resulting page. The messages stored this way are saved in the the current request so that they are available during page rendering.

Adding messages to the page this way won't work anymore if your are returning an action outcome with the pretty: prefix. In this case the page won't be rendered in the same request but the user will be redirected to a completely new URL. As the messages added to the FacesContext are stored on request level they won't be available in the new request and so will get lost.

Fortunately there is a way to work around this issue. PrettyFaces contains a phase listener called MultiPageMessagesSupport that will save the FacesMessages before the redirect occurs and restore them on the next request.

To include the MultiPageMessagesSupport phase listener in your application, just add the following lines to your faces-config.xml.

<lifecycle>
  <phase-listener>com.ocpsoft.pretty.faces.event.MultiPageMessagesSupport</phase-listener>
</lifecycle>

There are several commonly used rewriting features that PrettyFaces provides for you: manipulating trailing slashes, upper and lower-casing, custom regex search and replace, and redirect types such as '301 - Permanent' and '302 - Temporary'.

<rewrite trailingSlash="append" toCase="lowercase" redirect="301"/>
<rewrite match="/foo" substitute="/bar" redirect="301"/>

The two rules above will cause ALL inbound and outbound URLs be appended with a trailing slash (if necessary,) but because of the "match" attribute, only URLs containing '/foo' will be replaced with '/bar/. Inbound URL-rewriting changes the browser URL unless the redirect attribute is set to “chain”:

<rewrite toCase="lowercase" redirect="chain" />

Each <rewrite /> rule may specify a match="..." attribute. This attribute defines which URLs will and will not be transformed by a given rewrite rule.

<rewrite match="/foo" trailingSlash="append" toCase="lowercase" />

Once a URL has been matched, regex groups may be used to perform value-substitution on the URL; this effectively takes parts of the original URL, and makes them availible in its replacement.

<rewrite match="/foo/(\w+)/" substitute="/bar/$1/" />

This is equivalent to calling the String method url.replaceAll("/foo/(\w+)/", "/bar/$1/"); Note, also, that the same type of substitution is available when issuing an external redirect from a rewrite-rule:

<rewrite match="/foo/(\w+)/" url="http://example.com/$1/" />

Click here for more detailed information on regular expressions in Java.

The table below outlines each of the individual rewrite-rule options:

public class CustomClassProcessor implements Processor {
	public static final String RESULT = "I PROCESSED!";

	public String process(final RewriteRule rewrite, final String url) {
		return RESULT;
	}
}

Given the following URL-mapping, we can render a pretty URL simply by invoking HttpServletResponse.encodeRedirectURL(String url):

<url-mapping id="viewCategory">
	<pattern value="/store/#{ cat : bean.category }/" />
	<view-id value="/faces/shop/store.jsf" />
</url-mapping>

For example:

HttpServletResponse response = getHttpServletResponse();
String rewrittenURL = response.encodeRedirectURL("/faces/shop/store.jsf?cat=shoes&lang=en_US")';

Or if using JSF:

String rewrittenURL = FacesContext.getCurrentInstance().getExternalContext()
			.encodeResourceURL("/faces/shop/store.jsf?cat=shoes&lang=en_US");

Will produce the following output URL:

/store/shoes/?lang=en_US

Notice that even though we did not define a managed query-parameter, the resulting URL still contains the 'lang' parameter. This is because PrettyFaces only rewrites the named path-parameters defined in the URL-pattern; all other query-parameters are simply left unchanged.

Given the following URL-mapping, some of our JSF URLs will automatically be rewritten:

<url-mapping id="viewCategory">
	<pattern value="/store/#{ cat : bean.category }/" />
	<view-id value="/faces/shop/store.jsf" />
</url-mapping>

For example:

<h:link outcome="/faces/shop/store.jsf" value="View category: Shoes>
	<f:param name="cat" value="shoes" />
	<f:param name="lang" value="en_US" />
</h:link>

And:

<h:link outcome="pretty:viewCategory" value="View category: Shoes>
	<f:param name="cat" value="shoes" />
	<f:param name="lang" value="en_US" />
</h:link>

Will both produce the same output URL:

/store/shoes/?lang=en_US

Notice that even though we did not define a managed query-parameter, the resulting URL still contains the 'lang' parameter. This is because PrettyFaces only rewrites the named path-parameters defined in the URL-pattern; all other query-parameters are simply left unchanged.

Outbound URL-rewriting may be disabled on an individual mapping basis, by using the attribute outbound="false".

<url-mapping id="viewCategory" outbound="false">
	...
</url-mapping>

PrettyFaces provides a JSF component to output an HTML link to the page. The link tag requires a mapping-id (specified in the pretty-config.xml,) identifying which link to render.

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

<%@ taglib prefix="pretty" uri="http://ocpsoft.com/prettyfaces" %>
 
<pretty:link mappingId="viewItem">
	<f:param value="#{item.category}" />
	<f:param value="#{item.id}" />
	View Item. (This is Link Text)
</pretty:link>

 /store/shoes/24

PrettyFaces provides a JSF component to generate a URL for use as a page scoped variable through El. This tag requires a mapping-id (specified in the pretty-config.xml)

<url-mapping id="viewItem">
	<pattern value="/store/#{ cat : bean.category }/#{ iid : bean.itemId }/" />
	<query-param name="language"> #{ bean.language } </query-param>
	<view-id value="/faces/shop/item.jsf"/> 
	<action>#{bean.loadItem}</action>
</url-mapping>

<%@ taglib prefix="pretty" uri="http://ocpsoft.com/prettyfaces" %>
 
<pretty:urlbuffer var="itemListURL" mappingId="viewItem">
	<f:param value="shoes" />
	<f:param value="24" />
	<f:param name="language" value="en_US" />
</pretty:urlbuffer>
<h:outputText value="Generated URL Is: #{requestScope.itemListURL}" />

 /store/shoes/24?language=en_US

Because PrettyFaces provides out-bound URL-rewriting, one can actually use standard JSF components such as <h:outputLink> in JSF 1.x, or <h:link> in JSF 2.x.

<url-mapping id="viewItem">
	<pattern value="/store/#{ cat : bean.category }/#{ iid : bean.itemId }/" />
	<query-param name="language"> #{ bean.language } </query-param>
	<view-id value="/faces/shop/item.jsf"/> 
	<action>#{bean.loadItem}</action>
</url-mapping>

<%@ taglib prefix="h" uri="http://java.sun.com/jsf/html" %>
 
<h:outputLink value="/faces/shop/item.jsf">
	<f:param name="cat" value="shoes" />
	<f:param name="iid" value="24" />
	<f:param name="language" value="en_US" />
</h:outputLink>

 /store/shoes/24?language=en_US

<url-mapping id="viewItem">
	<pattern value="/store/#{ cat : bean.category }/#{ iid : bean.itemId }/" />
	<query-param name="language"> #{ bean.language } </query-param>
	<view-id value="/faces/shop/item.jsf"/> 
	<action>#{bean.loadItem}</action>
</url-mapping>

<h:link outcome="/faces/shop/item.jsf">
	<f:param name="cat" value="shoes" />
	<f:param name="iid" value="24" />
	<f:param name="language" value="en_US" />
</h:link>

<h:link outcome="pretty:viewItem">
	<f:param name="cat" value="shoes" />
	<f:param name="iid" value="24" />
	<f:param name="language" value="en_US" />
</h:link>

 /store/shoes/24?language=en_US

It may sometimes be necessary to provide custom configuration options in PrettyFaces. Loading URL-mappings from a database, for example, or generating mappings based on the state of the file-system. Due to this requirement, PrettyFaces offers an extension point for configuration providers to supply their own additional configuration to be merged with the master configuration at the time when PrettyFaces boots up. This is when you would implement a custom ConfigurationProvider.

public class MyConfigurationProvider implements ConfigurationProvider {
   
   public PrettyConfig loadConfiguration(ServletContext servletContext)
   {
      // add new configuration elements here
      return new PrettyConfig(); 
   }
}

To let PrettyFaces know about your provider, you'll have to register your implementation by creating a file named META-INF/services/com.ocpsoft.pretty.faces.spi.ConfigurationProvider in your classpath and add the fully-qualified class name of your implementation class there.

         META-INF/services/com.ocpsoft.pretty.faces.spi.ConfigurationProvider
         com.example.MyConfigurationProvider
       

After all configurations have been loaded and merged from any built-in or registered ConfigurationProvider sources, there is an additional opportunity to post-process the entire configuration, for instance, if you wanted to programmatically add security constraints to mappings based on various patterns. This is when you would implement a custom ConfigurationPostProcessor.

public class MyPostProcessor implements ConfigurationPostProcessor {
   
   public PrettyConfig processConfiguration(ServletContext servletContext, PrettyConfig config)
   {
      // make changes to the configuration here
      return config; 
   }
}

To let PrettyFaces know about your post-processor, you'll have to register your implementation by creating a file named META-INF/services/com.ocpsoft.pretty.faces.spi.ConfigurationPostProcessor in your classpath and add the fully-qualified class name of your implementation class there.

         META-INF/services/com.ocpsoft.pretty.faces.spi.ConfigurationPostProcessor
         com.example.MyPostProcessor
       

As part of the Annotations scanning (one of PrettyFaces' configuration methods,) it may sometimes be necessary to integrate with a custom bean-container that is not one of the built in containers supported natively. It is in these cases when you should implement a custom ELBeanNameResolver. The following example shows a resolver that will resolve the bean name by searching for a @Named annotation.

public class MyBeanNameResolver implements ELBeanNameResolver {
   
      public boolean init(ServletContext servletContext, ClassLoader classLoader) {
         // tell PrettyFaces that initialization was successful
         return true;
      }
   
      public String getBeanName(Class<?> clazz) {
         
         // try to find @Named annotation
         Named annotation = clazz.getAnnotation(Named.class);
         
         // return name attribute if annotation has been found
         if(annotation != null) {
            return annotation.value();
         }
         
         // we don't know the name
         return null;
         
      }
      
   }

To let PrettyFaces know about your resolver, you'll have to register your implementation by creating a file named META-INF/services/com.ocpsoft.pretty.faces.spi.ELBeanNameResolver in your classpath and add the fully-qualified class name of your implementation class there.

         META-INF/services/com.ocpsoft.pretty.faces.spi.ELBeanNameResolver
         com.example.MyBeanNameResolver