eXo Platform comes with a set of advanced portlets to build rich applications quickly. But you may want to develop your own portlets to fit your needs.

The development of a portlet using the raw portlet API can be a bit painful; it is often preferable to use a higher-level framework such as JSF. JSF is a request-driven MVC web framework based on a component-driven UI design model, and is part of the JEE standard.

This article is the first of a set of three tutorials that will teach you how to develop a portlet with JSF 2.0 and RichFaces 4, and leverage eXo Platform content and social capabilities.

RichFaces is a set of advanced JSF components that will allow us to add even more richness to our applications.

The source code of this first tutorial is available here.

Prerequisites

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 latest version of the Portlet Bridge (3.0.0.Beta1 at the time of writing). Type the following command:

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

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

portlet.xml

  • Change the portlet-app tag as follows:
  • Move the portlet-info tag under the supports tag.
  • faces-config.xml

  • Remove everything under the faces-config tag:
  • pom.xml

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

    with the new value. For example:

    Your project is now ready, and can be built to be deployed in eXo Platform. You can 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 eXo Platform

    The next step is to deploy the portlet in eXo Platform. To do so:

    • Start eXo Platform 3.5;
    • Once started, copy the war file of the portlet into the webapps directory. If the portlet deploys correctly, you should see the following lines in the console:

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

    • Go to http://localhost:8080/portal/private/acme;
    • Connect with john/gtn;
    • Go to the Application menu;

    • Click on Portlets. The list of all the deployed portlets is available on the left side. We will now make the portlet addable to 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 contain 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 the other fields as they are. Note that you can easily define titles in other languages;
    • Click on Next;
    • We will use the default empty dashboard, so click on Next;
    • In the portlet catalog, find the RiPortlet and drag it onto 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:

    Then, add the following lines to your web.xml:

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

    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 from the RichFaces demo website. Just edit the src/main/webapp/home.xhtml file and add these lines before </h:body>:

    Build your war file and copy/paste it into eXo Platform’s webapps directory. There’s no need to restart; the portlet is hot-redeployed!

    You should see the following message in the console:

    Just reload your portal page and the tabPanel component will appear:

    Your JSF/RichFaces portlet is now fully working!

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

    This tutorial has shown you how to create your own portlets easily using JSF, a standard Java web framework.

    The next tutorials will show you how to leverage eXo Platform features in your business portlets.

    (original article from Thomas blog)