Liferay is a Gartner Magic Quadrant Leader for the Sixth Year! Find out why
« Back to Development

Develop Vaadin Apps as Portlets

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.

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
error when trying to use the portlet. You can do this in the Java Compiler and Project Facets sections of the properties of your project. This error looks like this e.g. in the tomcat console:

Resources #

12 Attachments
111582 Views
Average (2 Votes)
The average rating is 4.5 stars out of 5.
Comments
Threaded Replies Author Date
Nice article! Thank you, Teemu. Jonas Yuan October 9, 2009 5:47 AM
Well done! Milan Jaroš October 13, 2009 11:02 AM
This ist not working with the current version... Kolja Köster March 12, 2010 2:03 AM
I tried the Trunkversion, Version 5.3 and... Kolja Köster March 12, 2010 5:58 AM
Solved this, due to a Java compiler version... Kolja Köster March 16, 2010 5:36 AM
tanks. i have a problem. i am trying to write... mokhtar hatampoor March 30, 2011 4:00 AM
Very informative ! Thank you!!!! Sudarshan Kumar May 27, 2011 3:34 AM
In Response to "Why is my application not... Matthew Yanchek May 27, 2011 8:05 AM
Nice one !!! Tejas Kanani June 2, 2011 1:50 AM
thank you nice article Ali Aharbil August 26, 2011 11:31 AM
When is the widgetset folder created? I don't... Thomas BERNARD September 30, 2013 8:46 AM
Very useful information, thanks! Alexey Bykov May 30, 2014 4:53 PM

Nice article! Thank you, Teemu.
Posted on 10/9/09 5:47 AM.
Posted on 10/13/09 11:02 AM.
This ist not working with the current version of Vaadin 6.2.5. Or this is a problem because of the trunkverion of Liferay I have currently installed. I can reproduce all the steps in this article, my war-file is created with liferay spcific xml-files, but deploying it fails with some DeploymentException. I am sorry to say this, but this is AGAIN a guide, that can not be reproduced.
Posted on 3/12/10 2:03 AM.
I tried the Trunkversion, Version 5.3 and Version 6 of Liferay. Still the approach in this article is not working. The option to 'Create portlet configuration' on the third screenshot is no longer aviable in the Vaadin Eclipse plugin. However, Liferay specific file are created, but I have no idea, if they are correct. Deploying the WAR-file fails with a HotDeployException. Trying to deploy the example mail-portlet in Liferay6 does not do anything, deployment stops after copying the war-file from the deploy folder.
Posted on 3/12/10 5:58 AM in reply to Kolja Köster.
Solved this, due to a Java compiler version conflict. I edited the according part in this article, to make it a bit more obvious. My screenshot looks horrible though, my apologies.
Posted on 3/16/10 5:36 AM in reply to Kolja Köster.
tanks. i have a problem.
i am trying to write a portlet that handle file uploading with vaadin.
in my code add file upload component done correctly but when i click upload button then don't enter in "receiveUpload" method to i do other tasks.
Posted on 3/30/11 4:00 AM.
Very informative ! Thank you!!!!
Posted on 5/27/11 3:34 AM.
In Response to "Why is my application not visible? " What if i don't want to define a pixel height? Say i want my portlet to use up the available remaining screen size? Setting it to 100% fails to work, even if i set it in the portlet.xml?
Posted on 5/27/11 8:05 AM in reply to Sudarshan Kumar.
Nice one !!!
Posted on 6/2/11 1:50 AM in reply to Matthew Yanchek.
thank you nice article
Posted on 8/26/11 11:31 AM.
When is the widgetset folder created?
I don't have it either I create a Vaadin Project or a Vaadin Portlet.
Posted on 9/30/13 8:46 AM.
Very useful information, thanks!
Posted on 5/30/14 4:53 PM.