Developing gCube Portlets Guide
Contents
- 1 Development of a gCube Portlet (GWT and Portlet)
- 2 Set the Portlet Context (How to get the logged in user's information)
- 3 Troubleshooting
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.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/
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