Difference between revisions of "Developing gCube Portlets Guide"

Revision as of 12:41, 8 July 2010

Development of a gCube Portlet

Prerequisites

• IDE: Eclipse 3.4+ J2EE with the following plugins installed
  • Portal Pack 2.0.1 [PPAC] get PPAC Eclipse Plugin
  • Google Eclipse Plugin [GECLIPSE] (If you want your portlet to use GWT) get GECLIPSE
  • GWT 2.03 (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="<b>gCube Applications</b>">
         <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

How to get the logged in user's information

The users that are logged in to the portal have certain information registered that can be retrieved using the Liferay's API.

long userid = Long.parseLong(request.getRemoteUser());
 
User user = null;
try {
        user = UserLocalServiceUtil.getUser(userid);
} catch (PortalException e) {
} catch (SystemException e) {
 
String username = user.getScreenName();   //Gets the username
String fullName = user.getFullName();     //Gets the fullname
String email = user.getEmailAddress();    //Gets the email address

The needed imports are:

import com.liferay.portal.model.User;
 
import com.liferay.portal.service.UserLocalServiceUtil;
 
import com.liferay.portal.service.UserService;
 
import com.liferay.portal.service.UserServiceUtil;
 
import com.liferay.portal.PortalException;
import com.liferay.portal.SystemException;

The jars that are needed can be found at $CATALINA_HOME/common/lib/ext and are the following:

• portal-kernel.jar
• portal-service.jar

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