Simple IT Mill Toolkit Portal Integration

Note
This tutorial is already somewhat outdated: since 5.2.0 portal support is now a core feature, more tightly integrated into IT Mill Toolkit. Many of the concepts described here are still relevant (liferay stuff, deployment, ...), but the integration is made more robust and there is a nice API; look in the com.itmill.toolkit.portlet -package.

See PortalTools

  1. Simple IT Mill Toolkit Portal Integration
    1. Introduction – Scope and Purpose
      1. Limitations
    2. QuickStart
    3. The Method
    4. Files
      1. Details
      2. Notes
    5. Step-by-step
      1. Installing
        1. Java
        2. Liferay
        3. Eclipse
        4. IT Mill Toolkit
      2. Making the Portlet
        1. Setting up the project
        2. Creating the code
        3. Configuring
      3. Deploying
    6. Adding features
    7. References

Introduction – Scope and Purpose

This article will show how to use IT Mill Toolkit to make a simple Portlet application, as defined by JSR-168. Specifically, we will make a Portlet to be deployed on Liferay, though it should be trivial to deploy on other Portlet Containers as well.

It is assumed that the reader has (at least basic) knowledge of Java, Portlet and Servlet technologies, and to some extent IT Mill Toolkit applications (the main ideas can be understood without knowledge in the latter.)

The purpose is to show a simple method to make a RIA/ajax IT Mill Toolkit application work in a Portlet environment. We will not be going into details about Portlet programming, or IT Mill Toolkit programming, and the code provided should be viewed as a starting point to expand upon.

Limitations

The method described below only allows one IT Mill Toolkit portlet per portal page. Adding multiple IT Mill Toolkit portlets to the same portal page will cause problems in the client side GWT rendering.

QuickStart

First get a Liferay bundle, install (unzip), and run (bin\startup.bat or bin/startup.sh)

Then deploy PortalApplication.war in Liferay by copying it to:

Add the DemoDynamicPortlet, enter "FeatureBrowser" as application, and set it's height to "500px". You can also try entering "Calc" or "DemoPortletApplication" as applications.

You can also skip ahead to the Step-by-step section.

The Method

The implementation consists of two main parts; an IT Mill Toolkit application and a portlet.

The portlet provides the actual portal integration; it communicates with the Portlet Container, and renders the initial UI code that "kickstarts" the ajax communication with the IT Mill Toolkit application, which is running as a servlet. The portlet also provides the servlet with portlet-specific functionality and data that might be needed, such as window state and user information.

The IT Mill Toolkit application does not necessarily need to be modified at all for this to work; however, in order to use portlet-specific data, it must communicate with the portlet. The servlet and portlet communicates via the user session, a method that requires the portlet and servlet to run in the same context. In practice, both servlet and portlet are packaged in the same WAR, which is then deployed as one web application.

Note that it is possible to access the servlet directly, bypassing the portlet, so the servlet should check this (e.g. portlet found in session, valid user logged in) if necessary.

Files

The main files are:

Details

The portlet is implemented in the DemoPortlet class, the IT Mill Toolkit application in the DemoPortletApplication class.

This particular example assumes the DemoPortletApplication is registered to the "root" of the context.

web.xml: 

<servlet-mapping>
   <servlet-name>DemoPortletApplication</servlet-name>
   <url-pattern>/*</url-pattern>
</servlet-mapping>

It is possible to modify this behavior; the writeAjaxWindow() -method in DemoPortlet can be modified to reference a specific servlet instead of the root of the context: 

request.getContextPath()

could be changed to 

request.getContextPath() + "/MyServlet"

One important detail to note when attempting this: The portlet and servlets must run in the same context (have the same context path). In Liferay you can avoid trouble by using the display-name in web.xml as filename for the WAR as well.

The communication between DemoPortlet and DemoPortlet works in the following way: DemoPortlet stores itself in a application-wide session attribute using a attribute name known to the DemoPortlet. The DemoPortlet can then fetch the DemoPortlet from the session, and invoke its methods. We're using the context name, plus optionally the name of the application (e.g /PortalApplication/ or /PortalApplication/DemoPortalApplication). DemoPortlet: 

// make portlet info accessible via session
PortletInfo uinfo = new PortletInfo(request.getPortletMode(), request
                        .getWindowState(), request.getUserPrincipal(), (Map) request
                        .getAttribute(PortletRequest.USER_INFO), config);
PortletSession sess = request.getPortletSession();
sess.setAttribute(sess.getPortletContext().getPortletContextName()
                                + "/" + app, uinfo, PortletSession.APPLICATION_SCOPE);

DemoPortletApplication: 

HttpSession ses = ((WebApplicationContext) getContext()).getHttpSession();
// the portlet has stored it's info there:
DemoPortlet.PortletInfo p = (DemoPortlet.PortletInfo) ses.getAttribute(ses
                              .getServletContext().getServletContextName()+ "/DemoPortletApplication");
if (p == null) {
   // not found, try w/o application name
   p = (DemoPortlet.PortletInfo) ses.getAttribute(ses.getServletContext().getServletContextName()+"/");
}

Also, for this to work properly in Liferay, the portlet must be "instanceable" but not "ajaxable". liferay-portlet.xml: 

<portlet>
   <portlet-name>DemoPortlet</portlet-name>
   <instanceable>true</instanceable>
    <ajaxable>false</ajaxable>
</portlet>

Notes

Some other important configuration issues to remember:

The portlet-name in portlet.xml and liferay-portlet.xml must be the same, and must match the id in liferay-display.xml.

The security-role-ref and role-mapping in portlet.xml and liferay-portlet.xml are not strictly necessary, but map general portlet roles to Liferay roles; refer to portal documentation for specifics.

Don't forget the portlet-info section in portlet.xml - Liferay tends to display "null" as name for the portlet if it's missing.

Step-by-step

Installing

We will be using Liferay, Eclipse, and IT Mill Toolkit.

Java

You'll need a Java JDK, get one from http://java.sun.com/javase/downloads/index.jsp and install.

Liferay

Official install documentation can be found here: http://www.liferay.com/web/guest/documentation/4_3/installation_and_customization#documents

In short:

  1. Get a Liferay “bundle” from http://www.liferay.com/web/guest/downloads/portal, we will be using Liferay 4.4.2 bundled with Tomcat 5.5.
  2. Install Liferay by uncompressing it in a suitable location – the created directory, for instance “R:\Projects\Portal\liferay-portal-tomcat-5.5-4.4.2”, will henceforth be referred to as <LIFERAY_HOME>
  3. Start Liferay by executing <LIFERAY_HOME>\bin\start.bat (or the equivalent on your platform)
  4. Verify by browsing to http://localhost:8080

Eclipse

There is a section called “Installing Eclipse IDE” in the IT Mill Toolkit reference manual, showing how to install Eclipse: http://www.itmill.com/documentation/itmill-toolkit-5-reference-manual/ch01s04.html#N204FA

IT Mill Toolkit

We will need the IT Mill Toolkit main JAR,(e.g. itmill-toolkit-5.1.0.jar - depending on the version used). The JAR can be found within the main distribution in the WebContent/WEB-INF/lib directory, or as a “Nightly Build”, both from http://www.itmill.com/downloads/itmill-toolkit.htm

Making the Portlet

Start Eclipse - we'll be staying in Eclipse until it's time to try the Portlet.

Setting up the project

  1. (optional) You may want to create a new Workspace in eclipse.

  1. Create a new project by choosing File->New->Project

  1. Select Web->Dynamic Web Project from the list and click “next”

  1. Name the project “PortalApplication” and leave the rest unchanged. “Finish”

  1. Copy the IT Mill Toolkit jar (e.g itmill-toolkit-5.1.0.jar) to the project's WebContent/WEB-INF/lib -folder in Eclipse.
  2. Right-click “PortalApplication” in the Tree-view to the left, and choose Build Path->Configure Build Path...

  1. Select Java Build Path th the left, select the Libraries -tab, and click “Add External Jars”
  2. Browse to <LIFERAY_HOME>\common\lib and choose servlet-api.jar. “Open”

  1. Click “Add External Jars” again, and choose <LIFERAY_HOME>\common\lib\ext\portlet.jar
  2. Click “Ok” on the Properties window.

Creating the code

  1. Right-click “PortalApplication” in the Tree-view to the left, and choose New->Class
  2. Enter a suitable package, name the class “DemoPortlet”, and add javax.portlet.Portlet as a Interface. “Finish”

  1. Right-click “PortalApplication” in the Tree-view to the left, and choose New->Class again.
  2. Enter a suitable package, name the class “DemoPortletApplication”, and enter com.itmill.toolkit.Application as superclass. “Finish”

  1. Open DemoPortlet (now found under Java Resources: src) and copy the code from DemoPortlet.java.
  2. Open DemoPortletApplication (now found under Java Resources: src) and copy the code from DemoPortletApplication.java.

Configuring

  1. Copy the contents of the web.xml provided here to your web.xml found in WebContent/WEB-INF.
  2. Create portlet.xml in WebContent/WEB-INF and copy the appropriate contents to it.
  3. Create liferay-portlet.xml in WebContent/WEB-INF and copy the appropriate contents to it.
  4. Create liferay-display.xml in WebContent/WEB-INF and copy the appropriate contents to it.

Deploying

  1. Right-click “PortalApplication” in the Tree-view to the left, and choose Export->WAR file...

  1. Set C:\Documents and Settings\<user name>\liferay\deploy as Destination (Vista: C:\Users\<user name>\liferay\deploy, Linux: /home/<user name>/liferay/deploy, Mac OS X: /Users/<user name>/liferay/deploy). “Finish”

  1. Bring up the console that Liferay created when you started it, and wait until it says “... Portlets for PortalApplication registered successfully”

  1. Browse to http://localhost:8080
  2. Sign in as test@liferay.com using the password “test”

  1. Add a page “test” (the “Add Page” link can be found in the upper right of the black area)

  1. Switch to your new, mostly empty, test page
  2. Choose Add application (from the upper right dropdown menu)

  1. Open up the “IT Mill Toolkit” section in the window that opened to the left

  1. Drag and drop the “DemoPortlet” to a suitable location on your page

Try signing in and out of Liferay, and maximizing the portlet: the application will update accordingly.

Adding features

DemoDynamicPortlet adds more functionality to the basic DemoPortlet. When you first add it to a page, a configuration UI is shown; you can show any application in the same context. The configuration can be changed in the portlet's edit mode. It uses PortletPreferences to store its configuration.

You can try this by deploying PortalApplication.war to Liferay. The WAR is preconfigured with three applications: DemoPortletApplication, Calc and FeatureBrowser. Try entering any of those into the DemoDynamicPortlet Application -field. Due to how the FeatureBrowser? is made (it only takes as much space as is given to it), you will have to set a height for it as well - try "500px" for instance.

You can also try following the "Importing IT Mill Toolkit as a Project" -section in the QuickStart with Eclipse, then adding DemoDynamicPortlet, then copying portlet.xml, liferay-portlet.xml and liferay-display.xml to WebContent/WEB_INF and replacing references to DemoPortlet with DemoDynamicPortlet. Then deploy using the WAR name "IT Mill Toolkit.war". You can now use all the IT Mill Toolkit demos in your portlet.

Java code: DemoDynamicPortlet

References

Attachments