Difference between revisions of "Developing gCube Portlets Guide"

Revision as of 15:10, 5 November 2016

Development of a gCube Mavenized Portlet (GWT and Portlet)

Preface

This guide is about how to create a Liferay portlet using GWT (Google Web Toolkit) and Maven on Eclipse IDE. In principle you could avoid using Maven, but it will make life easier, so let use it.
This guide was tested with Eclipse 4.4 Luna EE (3.7+ is supported), on Ubuntu 14.04 with Java 7. Official notes on how to combine GWT and Maven are available at the following link https://gwt-maven-plugin.github.io/gwt-maven-plugin/.

Prerequisites

• IDE: Eclipse Java EE IDE for Web Developers. Version: 3.7+
• Google Eclipse Plugin [GECLIPSE] (If you want your portlet to use GWT) GECLIPSE
  • GWT 2.7.0 SDK (Bundled with the above Plugin)
• m2e – maven integration for eclipse available here
• m2e-wtp – maven Integration for WTP available here

Project creation

Create a new maven project, when prompted for selecting the archetype type 'org.codehaus.mojo' and select the gwt-maven-plugin as shown in the picture below (select 2.7.0 if you use GWT 2.7):

Click next and enter the maven coordinates for your artifact, see below for an example:

Sample is going to be the entry point class of your gwt application.

Writing a GWT application

You can find useful information about how to write a gwt application on the GWT'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 the body of the HTML page.

Project First Run

Now you are ready to see it working! However, if you try to run it as Web Application, you will be warned about the fact that the web.xml file is not complete

Loading modules
   org.gcube.portlet.user.sample_portlet.*
      Validating <servlet> tags for module 'Sample'
         [WARN] Module declares a servlet class 'org.gcube.portlet.user.sample_portlet.server.GreetingServiceImpl 
with a mapping to '/Sample/Sample/greet', but the web.xml has no corresponding mapping;
please add the following lines to your web.xml:
<servlet-mapping>
  <servlet-name>greetServlet</servlet-name>
  <url-pattern>/Sample/Sample/greet</url-pattern>
</servlet-mapping>

Fix the web.xml file as specified above and retry, now your browser should start and you can try your first GWT mavenized application.

Adapting your Portlet to Liferay Portal

gCube 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). Moreover, you need to create a java class file that extends Liferay's GenericPortlet.

Suppose MyGCubePortletName is your portlet's name. Create a java class named MyGCubePortletNamePortlet whose content is the following:

 
public class MyGCubePortletNamePortlet extends GenericPortlet {
	public void doView(RenderRequest request, RenderResponse response)throws PortletException, IOException {
		response.setContentType("text/html");
		ScopeHelper.setContext(request);
	    PortletRequestDispatcher dispatcher = 
                   getPortletContext().getRequestDispatcher("/WEB-INF/jsp/MyGCubePortletNamePortlet_view.jsp");
	    dispatcher.include(request, response);		
	}
	public void processAction(ActionRequest request, ActionResponse response)
			throws PortletException, IOException {}
}

To access the GenericPortlet and the ScopeHelper classes add the following dependencies to your pom.xml

<dependency>
	<groupId>javax.portlet</groupId>
        <artifactId>portlet-api</artifactId>
	<scope>provided</scope>
</dependency>
<dependency>
	<groupId>org.gcube.portal</groupId>
	<artifactId>custom-portal-handler</artifactId>
	<scope>provided</scope>
</dependency>

We are going to create some other files, including "MyGCubePortletNamePortlet_view.jsp". Move into the directory src/main/webapps/WEB-INF, in which the web.xml file is located too. Here you need to:

• Create two empty xml files 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

• Create a directory named jsp
  • add the file MyGCubePortletName_view.jsp inside the just create directory.

Content for the above files

• portlet.xml

This file could contain more than one <portlet> tag, in this case we suppose there is only one

<?xml version="1.0"?>
<portlet-app
	version="2.0"
	xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd 
        http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">
	<portlet>
		<portlet-name>MyGCubePortletName</portlet-name>
		<display-name>MyGCubePortletName</display-name>
		<portlet-class>MyGCubePortletName</portlet-class>
		<init-param>
			<name>view-jsp</name>
			<value>/view.jsp</value>
		</init-param>
		<expiration-cache>0</expiration-cache>
		<supports>
			<mime-type>text/html</mime-type>
		</supports>
		<portlet-info>
			<title>Share updates</title>
			<short-title>Share</short-title>
			<keywords>Share Updates</keywords>
		</portlet-info>
		<security-role-ref>
			<role-name>administrator</role-name>
		</security-role-ref>
	</portlet>
</portlet-app>

• 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 6.2.0//EN" 
  "http://www.liferay.com/dtd/liferay-portlet-app_6_2_0.dtd">
<liferay-portlet-app>
	<portlet>
		<portlet-name>MyGCubePortletName</portlet-name>
		<layout-cacheable>false</layout-cacheable>
		<instanceable>false</instanceable>
		<ajaxable>false</ajaxable>
                <!-- LOCATION CSS HERE -->
		<header-portlet-css>/MyGCubePortletName.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 6.2.0//EN" 
 "http://www.liferay.com/dtd/liferay-display_6_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= Author's name
licenses=EUPL

• JSP file's content

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

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

Maven Goals (Create your Web Archive)

• goal gwt:compile
  • GWT Compile mode In order to gwt:compile your portlet create a Maven Build Configuration and enter gwt:compile on the goal text box.

• goal package
  • package will generate the war for you in the target folder.

• goal deploy
  • to use the deploy goal please refere to the gCube Maven Guide as you would need to create a distro folder with specific files in it.

Download the sample project

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

File:SamplePortletProject.tar.gz

Or you can download the source code from the following link (from gCube SVN Repository)

Sample Project SVN Link

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

For gCube versions lower than 4.2

In order to get a GCube Portlet work into the portal you need to pass it the context in which the portlet is running into. In fact, we add the org.gcube.portal.custom-portal-handler module dependency to our pom.xml file project.

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 context in the session (user, scope, token) 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();

For gCube versions higher or equal than 4.2

A new way of performing this operation (plus some others) is available starting from this release. See here for more information. Basically, you no longer need to use the ScopeHelper, but the ClientContext library. So, the new doView looks like

public void doView(RenderRequest request, RenderResponse response)    throws PortletException, IOException {
    PortletRequestDispatcher dispatcher = getPortletContext().getRequestDispatcher(....);
    dispatcher.include(request, response);
}

Migrating from Liferay 6.0 to Liferay 6.2.5

Main changes to deploy portlets

Starting from gCube 4.0.0, Liferay 6.2.5 will be used. In order to deploy portlets on the new version, some changes have to be done. If you were using an old Liferay version, please check and change if needed the following files (location of these files is in your project src/main/webapp/WEB-INF folder):

• DTD declaration into liferay-display.xml replace with

<!DOCTYPE display PUBLIC "-//Liferay//DTD Display 6.2.0//EN" 
  "http://www.liferay.com/dtd/liferay-display_6_2_0.dtd">

• DTD declaration into liferay-portlet.xml replace with

<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 6.2.0//EN" 
  "http://www.liferay.com/dtd/liferay-portlet-app_6_2_0.dtd">

• <web-app> tag into web.xml replace with

<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
          http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
	version="3.0">

UserManagement Library 2.0

The UserManagement library must be used to manage users, groups (VREs) and roles. You are discouraged to use Liferay's API directly, because of different abstractions made upon such concepts by the gCube framework.

The library offers APIs to manage Liferay's Users, Roles and Groups using the associated managers (i.e., to manage users you need to instanciate the UserManager and so on).

With respect the previous version of the library:

• VRE, VO e RootVO are no longer modelled as Organisations in Liferay, rather they are modelled as Sites;
• GCubeUser (replaces UserModel), GCubeGroup (replaces GroupModel), GCubeRole replaces (RoleModel) now contain Liferay's User, Group and Role information respectively;
• GCubeTeam has been introduced to support something similar to a Role, but restricted to a particular VRE. A role, instead, is available in any VRE.

For more information and examples look at the dedicated page.

PortalManager 2.0

The gCube Portal Manager is a component all portlets need to use to get the context where they are running. The new version 2.0 offers other facilities. See here for more details.

ASL Social 1.0

The ApplicationSupportLayer is a library that uses the SocialNetworkingLibrary one to offer services to portlets (e.g. notification mechanisms).

The new version has a main change into the ApplicationNotificationsManager: it no longer requires the AslSession.

The new constructor requires :

• SocialNetworkingSite site filled with the required data
• String scope; // the current scope
• SocialNetworkingUser currUser. // the current user

see also: ASL Notifications examples

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

• While deploying the generated .war in Liferay, you get

ERROR [MinifierFilter:136] java.lang.NullPointerException

Solution(s) : Open your .gwt.xml, the rename-to attribute value of <module> for some unknown reason must be lowercase. If the above didn't work also having the same gwt-module name and the portlet class name would make the Minifier crashing.If none of the above worked also having the same gwt-module name and portlet id name (in WEB-INF xml files) would make the Minifier crashing.

• When moving to Liferay 6.2.5 you need to update the web.xml's <web-app> tag. After having changed it, Eclipse gives this error

Description Resource Path Location Type Cannot change version of project facet Dynamic Web Module to 3.0.

Solution: go to Window > Show View > Navigator, under the .settings directory of the project, there is a file named org.eclipse.wst.common.project.facet.core.xml, find the jst.web facet and change it to version 3.0. Now make a maven update and the error should be fixed.