Introduction #

Vaadin is a framework for building rich internet applications which can be run as standalone web applications or as portlets. Liferay 6 includes support for Vaadin, but you can also deploy Vaadin application into Liferay 5.2.x portal.

This tutorial explains how to create a Vaadin application that can be run as a Liferay portlet by using the Vaadin Eclipse plugin.

Prerequisites #

To complete this tutorial you should install the following software on your environment.

• Eclipse IDE for Java EE Developers
• Liferay Portal 6.x.x

Or you can use an older Liferay 5.2.x version, but in this case you must complete the Vaadin installation as described at the end of this tutorial.

Installing the Eclipse plugin #

The easiest way to create Vaadin portlets is to use the Vaadin Eclipse plugin. Install the latest version of the Eclipse plugin (version 1.2.1 at the time of writing) by adding the following update site URL to your Eclipse. By opening the same URL in your browser, you get more detailed installation instructions.

http://vaadin.com/eclipse

Create a New Vaadin Project #

First we need to create a new Vaadin project. You can do this by selecting New -> Project... -> Vaadin Project.

Next you must give a name for the project (I'll use HelloVaadin). And you must select Generic portlet (Portlet 2.0) as the deployment configuration. Select the latest Vaadin version (6.4.3 at the time of writing). If the wizard suggest an older version, you should click the Download... button to download the latest release.

You can use the default settings on all of the next stages. After the wizard completes, you should have a new project in your workspace with the name HelloVaadin. As we selected the Generic portlet (Portlet 2.0) deployment configuration, the plugin has automatically generated the following configuration files under the WebContent/WEB-INF directory.

• liferay-display.xml
• liferay-portlet.xml
• portlet.xml
• liferay-plugin-package.properties

Also the plugin generates a simple Hello World style Vaadin application inside the src directory.

Deploying the Application as a Portlet #

The example project is now ready to be deployed into Liferay. Startup your Liferay portal and after it's running right-click the project and select Export... -> WAR file. Select the deploy directory of your Liferay installation as the target directory to directly hot-deploy the Vaadin application.

After you see the "1 portlet for HelloVaadin is available for use" message on the Liferay logs, you can login as Bruno (or any other user with the administrator role) and add the portlet application into your portal.

Deploying the Application as a Web Application #

You can easily deploy and debug the same application also as a web application outside the portal.

Open the Servers view on your Eclipse. If you haven't defined any servers, you should do it now. After defining a server (I'll assume Tomcat here), right-click the Tomcat and select Add and Remove... to add the HelloVaadin project to be run in the Tomcat. Start the Tomcat server and open your browser with the URL http://localhost:8080/HelloVaadin/HellovaadinApplicationServlet to run the Vaadin application without the portal.

Vaadin Installation on Liferay 5.2.x #

If you are using an older Liferay 5.2.x version of the portal, you must manually install the shared Vaadin library jar and shared resources.

1. Download and unzip the full Vaadin zip package from http://vaadin.com/download.
2. Copy the vaadin-6.x.x.jar file (found in the WebContent/WEB-INF/lib directory) to LIFERAY_HOME/tomcat-6.0.18/webapps/ROOT/WEB-INF/lib/vaadin.jar. Notice that you must remove the version information from the filename.
3. Copy the VAADIN directory and all subdirectories (found under the WebContent directory) into LIFERAY_HOME/tomcat-6.0.18/webapps/ROOT/html.
4. Next you must create (or edit) your portal-ext.properties file (in the LIFERAY_HOME/tomcat-6.0.18/webapps/ROOT/WEB-INF/classes directory) and add the following lines so that the Vaadin application knows where to find the theme and widgetset resources.

vaadin.resources.path=/html
vaadin.theme=reindeer
vaadin.widgetset=com.vaadin.portal.gwt.PortalDefaultWidgetSet

On deployment you should exclude the vaadin-6.x.x.jar file from the war package since now your portlets use the shared vaadin.jar. See the liferay-plugin-package.properties file for the source of the dependency.

Using Liferay IDE to Create Vaadin Portlet Plug-ins #

Liferay IDE simplifies the development of Vaadin portlets in Liferay 6.

When creating a new portlet plugin project most of the configuration is made by the Liferay IDE by creating a new "Liferay Portlet Plug-in Project".

For the minimal Vaadin portlet, the following files are relevant:

• liferay-plugin-package.properties
• Java class extending com.vaadin.Application
• portlet.xml

Adding Portlet Dependencies #

In order to use Vaadin (and Add-ons) they have to be in the classpath. This is configured in the liferay-plugin-package.properties

Creating a Vaadin Application #

Vaadin application is a Java file extending com.vaadin.Application class. An instance of this class in created for every user accessing the application. At this point the init() function is invoked to initialize user interface.

Here is a minimalistic Hello World sample with Vaadin:

package mypackage;

import com.vaadin.Application;
import com.vaadin.ui.Label;
import com.vaadin.ui.Window;

public class MyVaadinApplication extends Application {
	public void init() {
		Window w = new Window();
		setMainWindow(w);
		w.addComponent(new Label("Hello Liferay!"));		
	}
}

Configuring the portlet.xml #

In a portlet plugin using Vaadin the actual portlet class is always the same. The Vaadin application class (the one that is actually your application) is given as parameter for the portlet.

Here is an example:

	<portlet>
	<!-- … -->
	<portlet-class>com.vaadin.terminal.gwt.server.ApplicationPortlet2</portlet-class>
	<init-param>
		<name>application</name>
		<value>mypackage.MyVaadinApplication</value>
	</init-param>
	<!-- … -->
	</portlet>

Using Vaadin Add-ons #

In addition to Vaadin core components you can use all Vaadin add-on components] in your portlet plugin project. In Liferay environment the add-on libraries should be centrally installed into Liferay and not into the portlet plugin project itself.

Also the widgetset (the client-side part of Vaadin) is centrally installed in ROOT/html/VAADIN, so whenever you install new add-on widgets that must be recompiled. There is a Vaadin Control Panel portlet that helps you to choose and compile a new widgetset directly from your portal GUI.

Overall process using the Vaadin Add-ons in Liferay and Liferay IDE:

1. Install the Vaadin Control Panel portlet
2. Download and copy the add-on jar to ROOT/WEB-INF/lib
3. Add the dependency to jar in your projects liferay-plugin-package.properties
4. Use the Vaadin Control Panel to recompile the widgetset (i.e. client-side widgets)
5. Use the Add-on in your project and

More detailed instructions for using the add-ons in the Vaadin Directory help

Troubleshooting #

Why is my application not visible? #

Check if you have defined the height of the main layout of your application as percentages. The portlet height might be zero and therefore heights defined as percentages are also zero. You can fix this by defining the height in pixels (e.g. setHeight("500px")).

java.lang.UnsupportedClassVersionError Exception #

You also need to make sure the compiler compliance level is set to 1.5 and the project Java Facet is at version 5.0 if you're using the default 1.5 JRE provided in the Liferay 5.2.x installation package. Otherwise you'll get

java.lang.UnsupportedClassVersionError: Bad version number in .class file

Resources #

• Vaadin
• Vaadin Directory for Add-ons
• Book of Vaadin - Vaadin manual
• Vaadin Eclipse plugin - Eclipse IDE integration plugin
• Mail Portlet example
• http://vaadin.com/web/sami/liferay - Vaadin applications in Liferay blog post
• Code, Deploy and Test with Liferay and Vaadin - Screencast @ Youtube
• Vaadin Mail Portlet Tour on Liferay - Screencast @ Youtube