JSF 2 / RichFaces portlet in eXo (Part 1/3)

eXoPlatform comes with a set of advanced portlets to quickly build rich applications. But you may want to develop your own portlets to fit your needs.
The development of portlet using the raw portlet API can be a bit painful. It is often interesting to use a higher level framework such as JSF. JSF is a request-driven MVC web framework based on component-driven UI design model, and is part of the JEE standard.

This article is the first part of a 3-steps tutorials which will learn you how to develop a portlet with JSF 2.0 and RichFaces 4, and leverage eXo Content and eXo Social capabilities.
RichFaces is a set a advanced JSF components which will allow us to add even more richness to our application.

The source code of this first part is available here.

Prerequisites

  • Download the latest version of eXo Platform 3.5.
  • Install and configure Apache Maven.

To be able to run a JSF application in a portal context, we need a JSF Portlet Bridge. This technology is also part of the JEE standard, and thus several implementations are available. For this tutorial the JBoss implementation will be used, but you don’t have to install anything as it will be added as a library in your portlet via maven.

Creating the JSF Portlet Bridge project

The JBoss JSF Portlet Bridge project provides a maven archetype to easily create a fresh JSF Portlet Bridge project with JSF 2.0 and the last version of the Portlet bridge (3.0.0.Beta1 when this tutorial has been written). Type the following command :

mvn archetype:generate -DarchetypeGroupId=org.jboss.portletbridge.archetypes -DarchetypeArtifactId=2.0-basic -DarchetypeVersion=3.0.0.Beta1 -DgroupId=org.exoplatform -DartifactId=exo-jsfportletbridge-portlet

Maven will prompt you to change the default value of the project’s properties. You can leave the default values by simply pressing Enter.

Your project is now created. However some little changes need to be done to make it fully operational.

portlet.xml

  • change the portlet-app tag with the following :
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
             version="2.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd

http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">

  • move the portlet-info tag under the supports tag

faces-config.xml

  • remove everything under the faces-config tag :
<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="2.0">
</faces-config>

pom.xml

Optionnally, the pom.xml file can be updated to use the last available version of the JSF libraries by changing :

<properties>
  <jsf.version>2.0.3-b03</jsf.version>
</properties>

with the new value. For example :

<properties>
  <jsf.version>2.1.2</jsf.version>
</properties>

Your project is now ready and can be built to be deployed in eXoPlatform. You can now build your project by launching the following command at the root of your project : mvn clean install

A war file should be available in the target folder of your project (JSF2RIPortlet.war by default).

Deploying the portlet in eXoPlatform

The next step is to deploy the portlet in eXoPlatform. For so,

  • start your eXoPlatform 3.5
  • once started, copy the war file of the portlet in the webapps directory. If the portlet deploys correctly, you should see the following lines in the console :

2 janv. 2012 14:00:37 org.apache.catalina.startup.HostConfig deployWAR
INFO: Déploiement de l’archive JSF2RIPortlet.war de l’application web
2 janv. 2012 14:00:38 com.sun.faces.config.ConfigureListener contextInitialized
INFO: Initialisation de Mojarra 2.1.2 (FCS 20110610) pour le contexte «/JSF2RIPortlet»
2 janv. 2012 14:00:39 javax.portlet.faces.GenericFacesPortlet init
INFO: Init GenericFacesPortlet for portlet riPortlet
2 janv. 2012 14:00:39 javax.portlet.faces.GenericFacesPortlet calculateBridgeClassName
INFO: Bridge class name is org.jboss.portletbridge.AjaxPortletBridge

The portlet has been successfully deployed in eXoPlatform. It should now be added in a page of the portal :

  • click on Portlets. The list of all the deployed portlets is available on the left side. We will now make the portlet addable in the portal’s pages.
  • Select our portlet (RiPortlet in the JSF2RIPortlet category).
  • in the right part, click on “Click here to add this portlet to a category.”
  • select a category, Adoption for example

  • click on Save
  • come back to the acme site’s home page (My Sites > acme in the top bar)

The next step is to create a page to place our portlet :

  • in the top bar, click on Add Page in Edit > Page

  • in the left side, click on the up arrow to add the page at the root
  • in the right side, enter “comics-store” as the name and “Comics Store” as the display name (guess what this tutorial will deal with ? ;-)). Leave others fields as is. Note than you can easily define title in others languages.
  • click on Next
  • we will use the default empty dashboard, so click on Next
  • in the portlet catalog, find the RiPortlet and drag&drop it in the page

  • click on the Save icon (upper right)

The portlet is now available on our new page :

Adding RichFaces

RichFaces is a set of advanced JSF components. To use it in your project, edit your pom.xml file to add the following dependencies :

<dependency>
  <groupId>org.richfaces.ui</groupId>
  <artifactId>richfaces-components-ui</artifactId>
  <version>4.1.0.Final</version>
</dependency>
<dependency>
  <groupId>org.richfaces.core</groupId>
  <artifactId>richfaces-core-impl</artifactId>
  <version>4.1.0.Final</version>
</dependency>

then, add the following lines in your web.xml :

<context-param>
  <param-name>org.richfaces.resourceMapping.enabled</param-name>
  <param-value>false</param-value>
</context-param>

<context-param>
  <param-name>org.richfaces.skin</param-name>
  <param-value>ruby</param-value>
</context-param>

finally, in your JSF views, add the following namespace :

xmlns:a4j="http://richfaces.org/a4j" xmlns:rich="http://richfaces.org/rich"

You can now use all the RichFaces components in your pages.
As an example, we will add a tabPanel component to the page. The code is simply taken form the RichFaces demo website. Just edit the src/main/webapp/home.xhtml file and add these lines before </h:body> :

<rich:tabPanel switchType="client">
  <rich:tab header="Overview">
    RichFaces is a component library for JSF and an advanced framework for
    easily integrating AJAX capabilities into business applications.
    <ul>
      <li>100+ AJAX enabled components in two libraries</li>
      <li>a4j: page centric AJAX controls</li>
      <li>rich: self contained, ready to use components</li>
      <li>Whole set of JSF benefits while working with AJAX</li>
      <li>Skinnability mechanism</li>
      <li>Component Development Kit (CDK)</li>
      <li>Dynamic resources handling</li>
      <li>Testing facilities for components, actions, listeners, and pages</li>
      <li>Broad cross-browser support</li>
      <li>Large and active community</li>
    </ul>
  </rich:tab>
  <rich:tab header="JSF 2 and RichFaces 4">
    <p>We are working hard on RichFaces 4.0 which will have full JSF 2 integration. That is not all though, here is
    a summary of updates and features:</p>
    <ul>
      <li>Redesigned modular repository and build system.</li>
      <li>Simplified Component Development Kit with annotations, faces-config extensions, advanced templates
support and more..</li>
      <li>Ajax framework improvements extending the JSF 2 specification.</li>
      <li>Component review for consistency, usability, and redesign following semantic HTML principles where
possible.</li>
      <li>Both server-side and client-side performance optimization.</li>
      <li>Strict code clean-up and review.</li>
    </ul>
  </rich:tab>
</rich:tabPanel>

Build your war and copy/paste it in the webapps directory of eXoPlatform. No need to restart, the portlet is hot redeployed !
You should see the following message in the console :

2 janv. 2012 14:24:01 org.apache.catalina.startup.HostConfig deployWAR
INFO: Déploiement de l’archive JSF2RIPortlet.war de l’application web
2 janv. 2012 14:24:02 com.sun.faces.config.ConfigureListener contextInitialized
INFO: Initialisation de Mojarra 2.1.2 (FCS 20110610) pour le contexte «/JSF2RIPortlet»
2 janv. 2012 14:24:04 org.richfaces.cache.CacheManager getCacheFactory
INFO: Selected fallback cache factory
2 janv. 2012 14:24:04 org.richfaces.cache.lru.LRUMapCacheFactory createCache
INFO: Creating LRUMap cache instance using parameters: {facelets.DEVELOPMENT=false, org.richfaces.resourceMapping.enabled=false, javax.faces.FACELETS_VIEW_MAPPINGS=*.xhtml, org.richfaces.skin=ruby, javax.portlet.faces.RENDER_POLICY=ALWAYS_DELEGATE, javax.faces.STATE_SAVING_METHOD=server, javax.faces.DEFAULT_SUFFIX=.xhtml}
2 janv. 2012 14:24:04 org.richfaces.cache.lru.LRUMapCacheFactory createCache
INFO: Creating LRUMap cache instance of 512 items capacity
2 janv. 2012 14:24:04 org.richfaces.application.InitializationListener onStart
INFO: RichFaces Core Implementation by JBoss, a division of Red Hat, Inc., version v.4.1.0.Final
2 janv. 2012 14:24:04 javax.portlet.faces.GenericFacesPortlet init
INFO: Init GenericFacesPortlet for portlet riPortlet
2 janv. 2012 14:24:04 javax.portlet.faces.GenericFacesPortlet calculateBridgeClassName
INFO: Bridge class name is org.jboss.portletbridge.AjaxPortletBridge

Just reload your portal page, the tabPanel component appears :

Your JSF/RichFaces Portlet is now fully working !

You can notice that the style of the elements on the page has changed. This is due to the skin capabilities of RichFaces. You can easily change the style by changing the value of the context param org.richfaces.skin in the web.xml (you have set ‘ruby’ for this example). RichFaces comes with a set of ready-to-use skins, and you can of course create your owns.

This tutorial showed how to simply create your own portlets using JSF, a standard java web framework.
The next tutorials will show how to leverage eXoPlatform features in your business portlets.

About these ads

, , ,

  1. #1 by Renata on 20/11/2012 - 12:09

    Hello,
    It’s a really good tutorial!
    Thanks!

  1. Portlet Development in eXo Platform with JSF and RichFaces (Part 1/3) – Open Source Enterprise Social Platform | eXo Blog and News

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: