Portlet Development Guide

The following software packages, references and frameworks are used in developing Portlets for the CVRG. CVRG Portlets are 168 and 286 compliant and derive most of their complex components from IceFaces. IceFaces was chosen due to the imbedded AJAX features which allow for a more seamless and active user-interface. The links below will allow you to get additional information if you have questions about any of these.

IcesFaces

Sun MicroSystems

Eclipse

Apache

Portlet Framework/Architecture

For stability reasons, Eclipse was chosen as the IDE of choice for the CVRG. CVRG portlets are developed in version 3.3 (Europa) due to the availability of an IceFaces plugin. The steps below allow developers to start a new project within Eclipse for a CVRG Portlet. Use this link to download an example portlet project with backing beans: CVRG Example Portlet Project

1. Getting started (From within Eclipse):
   1. Right click in the project/Navigator view in eclipse
   2. Select Project
   3. Select the Web option
      1. Click Dynamic Web Project
   4. Click Next
2. Configuring basic project attributes:
   1. Enter your project name
   2. Verify the Target Runtime is “Apache Tomcat V6.0
      1. If it is not, then alter the selction to match above
   3. Verify the Configurations selection is “ICEfaces Project”
      1. If it is not, then alter the selection to match above
   4. Click Next
3. Select Your Project Facets
   1. Verify the Configurations drop down matches your previous selection
   2. Check the box next to Java Server Faces with version 1.1
   3. Check the box next IceFaces with version 3.0
   4. Set the Dynamic Web Module to 2.5 (hit the drop-down arrow and select 2.5)
      1. The ICEfaces Project defaults to Java 1.4, but a Web Module of 2.5 requires Java 5.0
      2. Change the Java from 1.4 to 5.0 (hit the drop-down arrow and select 5.0)
   5. Click Next
4. Review the Web Module settings – no changes need to be made
   1. Click Next
5. Review/Edit JSF Capabilities
   1. Edit the JSF Libraries
      1. Verify that the Server Supplied JSF Implementation is not selected.
         1. If it is selected, change to the other option
      2. Edit the selected Sun JSF library to be:
         1. Sun JSF RI v1.2_04
      3. Move the "Apache Commons Library" in Component Libraries from the left-hand side list to the right-hand side list.
         1. Highlight "Apache Commons Library" and click the ">" button.
   2. Click Next
6. Verify that no errors are identified with Deployed Libraries
   1. Click Finish
7. Portlets require concurrentDOMViews to be set to true
   1. Open the web.xml
   2. Find concurrentDOMViews in the web.xml
   3. Change the value from "false" to "true"

During the development phase, issues were encountered and recorded by the CVRG development staff. These are listed below with a cause and resolution (if applicable). If you have encounter new issues please refer them to sgranite@jhu.edu.

1. Session Expiration
   1. Description: Currently Icefaces and Liferay do not have an active method to share attributes through the session using the private-session-attributes tag
   2. Cause: use of the tag <private-session-attributes>false</private-session-attributes>
   3. Resolution: Active IceFaces issue - Liferay stomps on session for AJAX functionality, this issue will never be fixed. There is a workaround See Sharing attributes between portal and portlet below.
2. Eclipse Crashing
   1. Description: Eclipse crashes each time a pop up window appears for info/warning/error (s).
   2. Cause: a change to Firefox and XULRunner
   3. Resolution: Use the provided INI file for eclipse (http://wiki.cvrgrid.org/index.php/Administration:CVRG_Developer_Image).
3. Sharing attributes between portal and portlet
   1. Description: Icefaces portlets are currently unable to retrieve session attributes from a liferay portal.
   2. Cause: UNKNOWN
   3. Resolution: Use CVRGAttributesServlet within the example project and configure this servlet (your project's web.xml) as a Liferay PortalDelegateServlet. This servlet then acts as a proxy to allow for communication through the portal to the war containing your portlets.

1. What version of IceFaces should I use? 1.7.1
   1. There are known issues in 1.7.1 that are supposed to be fixed in 1.7.2
   2. It is always best to use the most currently available formal Release from Icefaces
2. Should I hot deploy a portlet project after changes without redeploying the portal?
   1. If the same portlets are in the war: You CAN remove the project folder from the TOMCAT container and just hot deploy – this is not recommended
   2. If you change the number of portlets in the war (Add or Subtract) then no: You must redeploy portal since the old entries in Liferay will not be removed cleanly.
3. How do I deploy my WAR file (From within Eclipse)
   1. Right click your project’s name from the Project or Navigator frame
   2. Select Export
   3. Verify that WAR file is selected
   4. Click “Next”
   5. Type the desired path and name for your WAR file
      1. Note this for future reference
   6. Click Next
   7. Click finish
   8. Exit Eclipse
   9. Open a new file browser window
      1. Navigate to the folder containing your WAR from step E.
   10. Copy the WAR file
   11. Navigate to /home/USERNAME/liferay/deploy
       1. Paste the WAR file
4. How do I share attributes between portlets within the same war
   1. Be sure to set the bean in the PortletSession.APPLICATION_SCOPE

PortletRequest request = (PortletRequest) FacesContext.getCurrentInstance().getExternalContext().getRequest(); 
PortletSession sess = request.getPortletSession(Boolean.FALSE);
sess.setAttribute("backingBean1", this,PortletSession.APPLICATION_SCOPE);

1. How do I retrieve attributes from the session
   1. In a bean create a method to pull the bean of choice out of session

protected static BackingBean1 getBackingBean1() {
ExternalContext etcx = FacesContext.getCurrentInstance().getExternalContext();
PortletSession psession = (PortletSession)etcx.getSession(false);
return (BackingBean1)psession.getAttribute("backingBean1", PortletSession.APPLICATION_SCOPE);
}

1. How can I verify if my WAR file has been deployed
   1. Open a new file browser window
      1. Navigate to the folder /opt/YOUR_TOMCAT_CONTAINER/webapps.
   2. Verify that the folder specified for your portlet(s) is there
   3. If it is not present you may refresh the folder
2. How do I Add a Portlet to the Portal for testing
   1. Sign in as a user with administrator priveleges
   2. Click the Welcome Banner
      1. Click the add Application options
   3. Select the appropriate grouping from the application menu
      1. This is WAR-specific
      2. There may be multiple sub groupings within a single WAR
   4. Select the desired Portlet and drag it to the frame on screen where you want it to be.
      1. Do not click the add button next to the portlet.
3. What XML configuration files are necessary to work with LifeRay
   1. Required:
      1. faces-config
      2. portlet
      3. web
      4. liferay-display
      5. liferay-portlet
   2. Optional
      1. liferay-plugin
4. Do my backing beans need to be Serializable?
   1. Yes – otherwise they can not be used on more than one page/Session and LifeRay will not handle them.
      1. When creating beans, you can separate out pieces into non Serializable classes, but the main class for a bean, must be serializable

1. What should my JSPX files look like?
   1. Copy the header and trailer below into your empty JSPX file
   2. Your code/components should go between them