Installing required libraries

Previous to start using JSF 4 Portlets we need to install the required libraries into our servlet container. This required libraries are bundled with the JSF 4 Portlets ditribution inside the /lib directory.

To get JSF 4 Portlets installed in your system follow below instructions depending on what servlet container are you using.

Tomcat users

Stop the Tomcat instance using the catalina.sh script.

Copy distributed libraries into directory [TOMCAT_HOME]/lib. The result must to be like following:

[TOMCAT_HOME]/lib/...
[TOMCAT_HOME]/lib/jsf4portlets-1.0-alpha-2.jar
[TOMCAT_HOME]/lib/commons-digester-1.8.jar
[TOMCAT_HOME]/lib/commons-beanutils-1.7.0.jar
[TOMCAT_HOME]/lib/commons-logging-1.1.jar

Start again the Tomcat instance and jump to next section!

GlassFish users

Stop the application server instance using the asadmin command:

asadmin stop-domain [domain_name]

Copy distributed libraries into /lib directory inside the domain tree. The result must be like the following.

[DOMAIN_HOME]/lib/...
[DOMAIN_HOME]/lib/jsf4portlets-1.0-alpha-2.jar
[DOMAIN_HOME]/lib/commons-digester-1.8.jar
[DOMAIN_HOME]/lib/commons-beanutils-1.7.0.jar
[DOMAIN_HOME]/lib/commons-logging-1.1.jar

Start again the application server instance and that's all!

Configuring JSF Portlet Applications

There are some configuration parameters that are required in order to start using JSF 4 Portlets. Those required parameters are explained as follows, other (optional) parameters are explained elsewhere.

Bridge initialization

The javax.portlet.faces.GenericFacesPortlet needs to know which Bridge class it must use to delegate work of processing requests.

During initialization, it checks for a portlet's init parameter: javax.portlet.faces.extension.bridgeClass. If this parameter is null, then it checks for the same parameter as a context initialization parameter. If no parameter is found, an javax.portlet.UnavailableException is thrown.

So, there are two ways for specify the bridge implementation: One application-wide using context initialization parameters, and, the another one is portlet specific.

Application Wide bridge configuration: web.xml

<web-app ...>

  <context-param>
    <param-name>
      javax.portlet.faces.BridgeClassName
    </param-name>
    <param-value>
      net.sf.jsf4portlets.BridgeImpl
    </param-value>
  </context-param>
  
</web-app>

Portlet Specific bridge configuration: portlet.xml

<portlet-app ...>

  <portlet>
    ...
    <init-param>
      <name>
        javax.portlet.faces.BridgeClassName
      </name>
      <value>
        net.sf.jsf4portlets.BridgeImpl
      </value>
    </init-param>
  </portlet>

</portlet-app>

Faces Configuration

You will also need to configure the standard FacesServlet: web.xml

<web-app ...>
   
   <servlet>
     <servlet-name>FacesServlet</servlet-name>
     <servlet-class>
       javax.faces.webapp.FacesServlet
     </servlet-class>
   </servlet>
   
   <servlet-mapping>
     <servlet-name>FacesServlet</servlet-name>
     <url-pattern>*.jsf</url-pattern>
   </servlet-mapping>
   
 </web-app>

JSF Portlet configuration

JSF 4 Portlet requires at least one parameter to be configured in portlet.xml for each portlet. This parameter is javax.portlet.faces.defaultViewId.view and it's needed to know the first view to be rendered when no viewId has been requested.

<portlet-app ...>

  <portlet>
    <portlet-name>...</portlet-name>
    <portlet-class>
      javax.portlet.faces.GenericFacesPortlet
    </portlet-class>
    
    <init-param>
      <name>javax.portlet.faces.defaultViewId.view</name>
      <value>/path/to/viewId</value>
    </init-param>
  </portlet>
</portlet-app>