Developing gCube Portlets Guide

Development of a gCube Portlet (GWT and Portlet)

Prerequisites

• IDE: Eclipse 3.4+ J2EE with the following plugins installed
  • Portal Pack 2.0.1 [PPAC] get PPAC Eclipse Plugin. The jars must be copied to the eclipse's plugin directory (Please Note: such plugin is already bundled with Eclipse 3.7 Indigo EE for Java developers)
  • Google Eclipse Plugin [GECLIPSE] (If you want your portlet to use GWT) get GECLIPSE
  • GWT 2.4.0 (Bundled with the above Plugin)

Creating an empty Portlet Project

• Create a new Dynamic Web Project using eclipse

• In the Wizard next step we are going to add support for Porlet 2.0. and specify Tomcat 5.5 as Target Runtime (Optional)

• Finally in the Wizard last step we change "Web Content" to "war" as Content Directory (To have ETICS and GWT2 Projects compatibility)

Portlet creation

To create your portlet using eclipse, click on your newly created project > New -> Other -> JavaPortlet.

You are also required to change your project default output folder from <MyGCubePortletName>/build/classes to <MyGCubePortletName>/war/WEB-INF/classes

If you performed the above procedure correctly now your project should look similar to the picture below:

---

You have created a Standard Portlet Project, to generate a war simple use the Eclipse Export > War Wizard

Adapting your Portlet to Liferay Portal

D4Science II Project as chosen to move to Liferay Portal from its 1.9 release. In order to make your portlet be deployable on Liferay you need to add some Liferay Portal specific deployment descriptor xml and property files. (In addition to the standard one for portlets, the portlet.xml)

Create two empty xml files into your project war WEB-INF folder and name them

• liferay-portlet.xml
• liferay-display.xml

Create 1 empty property file into your project war WEB-INF folder and name it

• liferay-plugin-package.properties

Content for the above files

<MyGCubePortletName> has to be changed with your actual portlet name

• liferay-portlet.xml

The elements that should be placed in that file must follow the exact order ... ...

<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 5.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_5_2_0.dtd">
<liferay-portlet-app>
	<portlet>
		<portlet-name>'''<MyGCubePortletName>'''</portlet-name>
		<layout-cacheable>false</layout-cacheable> <b>//for loading the new portlet</b>
		<instanceable>false</instanceable>    <b>//to use one portlet instance for the D4S portal</b>
		<ajaxable>false</ajaxable>  <b>//it is need for the correct rendering of the GWT portlet</b>
		<!-- LOCATION CSS HERE -->
                 <header-portlet-css>/css/test.css</header-portlet-css>
	</portlet>
	<role-mapper>
		<role-name>administrator</role-name>
		<role-link>Administrator</role-link>
	</role-mapper>
</liferay-portlet-app>

... ...

---

• liferay-display.xml

The element 'category' is recommended to use the name "gCube Applications"

<?xml version="1.0"?>
<!DOCTYPE display PUBLIC "-//Liferay//DTD Display 5.2.0//EN" "http://www.liferay.com/dtd/liferay-display_5_2_0.dtd">
   <display>
      <category name="'''gCube Applications'''">
         <portlet id="'''<MyGCubePortletName>'''" />
      </category>
   </display>

---

• liferay-plugin-package.properties

name=<MyGCubePortletName>
module-group-id=liferay
module-incremental-version=1
tags=
short-description=
change-log=
page-url=http://www.d4science.eu
author=D4Science EU
licenses=

---

If you performed the above procedure correctly now your project should look similar to the picture below:

Download this sample project

You can download this sample project complete with samples for the above files from the link below

File:MyGCubePortlet.tar.gz

The same project is available on the project's svn repository at this URL: http://svn.research-infrastructures.eu/public/d4science/gcube/trunk/portal/portal-framework/MyGCubePortlet/

---

Writing a GWT application

You can find useful information about how to write a gwt application on the Google Web Toolkit's official site: http://code.google.com/webtoolkit/.

! IMPORTANT INFO

In the entrypoint-class, in the onModuleLoad() method: When you are about to add your widget in the main page,
instead of writing:

RootPanel.get().add(<your widget>);

you must write:

RootPanel.get(<a unique id for the DIV>).add(<your widget>);

So, the generated html will be placed in the predefined div instead of being placed in an unspecified location.

Integrate a GWT2 Web Application Project

Adapting your GWT2 Project is now a straightforward procedure. (We assume you have the GWT Eclipse Plugin Installed)

To add GWT support to your project go to your Project Properties: Google -> Web Toolkit -> Use Google Web Toolkit

---

Now you have to copy some files from the GWT Project to the portlet project:

• copy your GWT src packages into your yet created Portlet Project
• copy your GWT war folder files into your war folder of the yet created Portlet Project e.g. .html,.css and the other folders of the war, except for WEB-INF
• Copy your GWT WEB-INF/web.xml file into your portlet war/WEB-INF/web.xml

You also have to edit the following files:

• In your GWT Project html file seek the following part:

<!--                                           -->
    <!-- This script loads your compiled module.   -->
    <!-- If you add any GWT meta tags, they must   -->
    <!-- be added before this line.                -->
    <!--                                           -->
    <script type="text/javascript" language="javascript" src="mygwtproject/mygwtproject.nocache.js"></script>

• Open your ./war/WEB-INF/jsp/LoginPortlet_view.jsp file and add the content of the <script> element above as shown below
  • Notice that request.getContextPath is added, together with the div using as id the unique name you specified in your entrypoint class

<portlet:defineObjects />
--%>
<script type="text/javascript" language="javascript" src='<%=request.getContextPath()%>/mygwtproject/mygwtproject.nocache.js'></script>

<div id="a unique id for the DIV">
</div>

---

• The CSS file Location of your GWT application must be set into the <header-portlet-css> element of the liferay-portlet.xml file as shown below (mygwtproject.css is in the war/ folder in this example)

<liferay-portlet-app>
	<portlet>
		<portlet-name>WebLogin</portlet-name>
		<icon>/icon.png</icon>
		<layout-cacheable>false</layout-cacheable>
		<instanceable>false</instanceable>
		<ajaxable>false</ajaxable> 
		<!-- LOCATION CSS HERE -->
                <header-portlet-css>/mygwtproject.css</header-portlet-css>
	</portlet>
	<role-mapper>
		<role-name>administrator</role-name>
		<role-link>Administrator</role-link>
	</role-mapper>
</liferay-portlet-app>

---

Compile GWT Inside the Portlet Project

You can now compile your GWT Application (Inside the portlet Project) by using the Eclipse Plugin as shown below

---

Set the Portlet Context (How to get the logged in user's information)

In order to get a GCube Portlet work into the portal you need to pass it the context in which the portelt is running into.

To do so: Get the latest version of the module org.gcube.portal.custom-portal-handler from ETICS.

CustomPortalHandler set the portlet context transparently to the developer (no need to call Liferay API as used to do in the past). Instead of asking for the username, it sets that in the session. So that the new doView() method will look like:

public void doView(RenderRequest request, RenderResponse response)    throws PortletException, IOException {
    ScopeHelper.setContext(request); // <-- Static method which sets the username in the session and the scope depending on the context automatically
    PortletRequestDispatcher dispatcher = getPortletContext().getRequestDispatcher(....);
    dispatcher.include(request, response);
}

Moreover, from within the GWT servlets you can get the current username from the http session using the ScopeHelper.USERNAME_ATTRIBUTE e.g.

HTTPSession httpSession = this.getThreadLocalRequest().getSession();
String sessionID = httpSession.getId();
String username =  httpSession.getAttribute(ScopeHelper.USERNAME_ATTRIBUTE).toString();

---

Create a Web Archive from Portlet Project

You can now create the Web Application Archive (WAR) using the export feature of Eclipse

Troubleshooting

General issues encountered by developers

• Once you try to compile your Dynamic Web Project GWT2 Powered you get the following exception

[ERROR] Unexpected
java.lang.NoSuchFieldError: reportUnusedDeclaredThrownExceptionIncludeDocCommentReference

Cause:  : Tomcat classpath is listed before your GWT classpath

Solution:  : Go to your Project Properties > Order and Export and make sure GWT SDK is listed before Tomcat one