Portlet Development

Portlet support in ICEfaces is now provided by the PortletFaces Bridge, an implementation of the JSR 329: Portlet 2.0 Bridge for JavaServer Faces. The portlet bridge specification technically applies to JSF 1.2 but the PortletFaces version been adapted to support JSF 2. The PortletFaces Bridge is tested and shipped with the ICEfaces 2 distribution and can be used to develop portlet applications with ICEfaces.

The version of the PortletFaces Bridge that is currently shipped with ICEfaces includes fixes that aren't available with the generally released version of the PortletFaces Bridge. This includes a fix for a conflict with WebSphere Portal when it attempts to write out the response status. It is anticipated that this issue will be resolved in a future PortletFaces Bridge official release. Ensure you use the copy of the library that ships with ICEfaces for all of your ICEfaces portlet deployments.
Support for WebSphere Portal is provided as part of ICEfaces EE (Enterprise Edition).

Examples

The following sample portlets are included in the ICEfaces distribution. The examples are useful for getting a quick start on how to build a portlet using ICEfaces and the PortletFaces Bridge. This includes what the markup should look like, what files need to be included, and how they should be configured.

For each portlet example, there is a corresponding non-portlet example. Looking under the [icefaces.dir]/samples, you'll find:

showcase/showcase
showcase/showcase-portlet

core/chat
core/chat-portlet

Each portlet example is built by using the content from the non-portlet sample and adding in the portlet-specific files required. Details for each sample are provide below.

Chat

The Chat example is a demonstration portlet that uses only stock JSF components and ICEpush. You can drop multiple instances on a single portal page and chat between the instances and between different browsers. The sample code is located under:

[icefaces.install.dir]/icefaces/samples/core/chat-portlet

To build a portlet .war file for Liferay 6 running on Tomcat 6.0, you execute the following ant command from the chat-portlet directory:

[icefaces.install.dir]/icefaces/samples/core/chat-portlet > ant clean liferay6.servlet-profile

The result is a portlet-compatible version of Chat located under:

[icefaces.install.dir]/samples/core/chat-portlet/build/dist/chat-portlet.war

This .war file can be deployed directly to the Liferay deploy directory. Once deployed, it will show up in the list of available portlets under the ICEfaces -> ICEpush category.

Showcase

The Showcase portlets are examples based on the ICEfaces Showcase example configured to run in a portal. It uses the same markup and code as the non-portlet demo, but with each component example delivered as an individual portlet. The sample is located under:

[icefaces.install.dir]/icefaces/samples/showcase/showcase-portlet

To build a portlet .war file for Liferay 6 running on Tomcat 6.0, you execute the following ant command from the chat directory:

[icefaces.install.dir]/icefaces/samples/showcase/showcase-portlet > ant clean liferay6.servlet-profile

The result is a portlet compatible version of Component Showcase located under:

[icefaces.install.dir]/icefaces/samples/showcase/showcase-portlet/build/dist/showcase-portlet.war

This .war file can be deployed directly to the Liferay deploy directory. Once deployed, it will show up in the list of available portlets under the ICEfaces3/Suite/ACE category.

Building Your Own Portlets

portlet.xml

ICEfaces makes use of the PortletFaces Bridge to handle the mapping of the portlet lifecycle onto the JSF lifecycle. This has many advantages like enabling proper resource handling and cleaner integration with the portal container. To define your portlet, take a look at the portlet definition of the chat portlet example:

    <portlet>
        <portlet-name>chat-ice2-portlet</portlet-name>
        <display-name>Chat</display-name>
        <portlet-class>org.portletfaces.bridge.GenericFacesPortlet</portlet-class>
        <init-param>
            <name>javax.portlet.faces.defaultViewId.view</name>
            <value>/chat.xhtml</value>
        </init-param>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
        </supports>
        <portlet-info>
            <title>ICEfaces 2 Chat</title>
            <short-title>ICEfaces 2 Chat</short-title>
            <keywords>icefaces portlet chat icepush</keywords>
        </portlet-info>
    </portlet>

The important parts are:

The portlet-class, which needs to be defined as org.portletfaces.bridge.GenericFacesPortlet.
The javax.portlet.faces.defaultViewId.view which should identify the page that is the initial view of the portlet.

web.xml

To prevent the processing of portlet resource URLs to avoid caching of things like bridge.js, the following parameter should be set to false.

<context-param>
    <param-name>org.icefaces.uniqueResourceURLs</param-name>
    <param-value>false</param-value>
</context-param>

Library Dependencies

The ICEfaces distribution includes a tested release version of the PortletFaces Bridge and is located in:

[icefaces.install.dir]/icefaces/lib/portlets

portletfaces-bridge-*.jar

Portlet Development