Difference between revisions of "Developing gCube Portlets Guide"

Revision as of 17:17, 5 November 2012

Development of a gCube Portlet (GWT and Portlet)

Prerequisites

• IDE: Eclipse Java EE IDE for Web Developers. Version: 3.7+
• Google Eclipse Plugin [GECLIPSE] (If you want your portlet to use GWT) get GECLIPSE
  • GWT 2.4.0 (Bundled with the above Plugin)

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.org
author=D4Science Org
licenses=EUPL

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/

• 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>

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

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