installation

Make sure you have the JSF API and apache-commons on your container classpath

Copy the following Jar files from the latest on-load release to your WEB-INF/lib directory or use maven to include the dependency.

web.xml

Tell the phase listener where to find the configuration file

<context-param>
  <param-name>onload-config</param-name>
  <param-value>/WEB-INF/onload-config.xml</param-value>
</context-param>
        

faces-config.xml

Register the phase listener with JSF.

Note: it is important to register this listener below the Seam phase listener when using the JBoss-Seam framework. This may also be the case with the Shale framework, but I have not tested Shale.

<lifecycle>
  ... Other phase listeners here ...
  <phase-listener>net.sf.jsfcomp.onload.OnLoadPhaseListener</phase-listener>
</lifecycle>
        

onload-config.xml

The source tree includes an example onload configuration file in the 'resources' directory. The structure is similar to that of the faces configuration file to keep the learning curve as small as possible.

The file consists of navigation rules. At most one navigation rule is executed per page load. The rule that matches the URL the most exactly is the rule that is processed. The first child node must be 'view-id'. This contains the path to the view (not the URL, so /file.xhtml instead of /file.jsf for example). The 'action' is an EL expression to a method reference. The optional 'success-result' specifies what outcome (in addition to null) defines a successful result.

view-id

The exact path to the view or a portion of the path ending with '*' to match the begging of a path. Examples: /myDir/myFile.xhtml, /myDir/my*, *

action

The EL expression. Example: #{myBean.myActionMethod}

success-result

If the result of an action is null or equal to the success result, nothing is done (the original/current view is processed). If the result is not equal to the success result or null, the result from the action is used to navigate to a new view based on the faces configuration file.

Example:

<?xml version="1.0" encoding="UTF-8"?>

<onload-config xmlns="urn:onload-config"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:onload-config onload-config.xsd">
  
  <navigation-rule>
    <view-id>/welcome.jsp</view-id>
    <action>#{bean.actionMethod}</action>
  </navigation-rule>
  <navigation-rule>
    <view-id>/path*</view-id>
    <action>#{bean.actionMethod}</action>
  </navigation-rule>
</onload-config>