NOTE: The following blog post is about Vaadin 6 and Liferay.  I'll be doing future posts on Vaadin 7, but for now I recommend sticking with Vaadin 6 in Liferay.

Introduction

About two years ago, I noticed the Liferay IDE allowed for the creation of a new type of portlet based on Vaadin.  Curious, I did some research and found I could create Liferay portlets based upon the Vaadin Framework.

According to the Vaadin FAQ, Vaadin ("Vaadin" sounds like vuh-din, emphasis on first syllable, the long 'a':s sound like the 'a' in "ago") is a Java web application framework. It is designed for creating rich and interactive applications that run in the browser, without any plugins. A server-driven architecture together with reusable component model is used to simplify programming of applications and for better web application security. No HTML, XML or JavaScript necessary and all Java libraries and tools are at your disposal.

Translation is that it's a framework that you do most of your development in Java and, since it is based on the GWT, runs mostly in the client browser and uses lots of AJAX to communicate with the backend.

It's not a flashy framework in that it's not really designed to support lots of browser eye-candy.  It is, however, very well suited for enterprise development where you want to support forms, tables, and other basic widgets to create real and responsive enterprise applications.

Unfortunately, the wizard in the Liferay IDE was the only info I found on creating Vaadin portlets.  I couldn't find a real developer guide, didn't understand some of the requirements from the Vaadin website, and I basically struggled through the development of an initial Vaadin portlet.

So this blog post is going to help explain Vaadin in Liferay and what you'll need to use to become an effective Vaadin portlet developer.

Terminology

Widgets

These are the UI elements that are rendered in the browser.  Vaadin includes support for a basic set of UI widgets and include buttons, checkboxes, option groups, tables, trees, labels, text fields, etc.

Widgets have two aspects: the server side code and the client side code.  The server side widget is referred to as a Component.  Components are instantiated, configured, and added to define what the client side will represent.  The client side code is in Javascript and is generated using GWT to compile the Java code for the components into the javascript version for the client side.

Widgetset

A widgetset is the set of compiled javascript for all of the widgets that are used in the Vaadin application.

Widgetsets have names.  The widgetset name is a Java class-like name complete with a package path, i.e. com.vaadin.portal.gwt.PortalDefaultWidgetSet.  There's actually a corresponding file in the classpath at the location defined by the widgetset name with the extension ".gwt.xml", and this file defines the widgetset and all included modules.  The com/vaadin/portal/gwt/PortalDefaultWidgetSet.gwt.xml file is read by the GWT compiler to compile the widgetset used on the client side.

A Vaadin application requires a correctly compiled widgetset for the Vaadin version used in the application to render the client side correctly.

Theme

Vaadin widgets are rendered in the browser using a theme.  Vaadin ships with a number of themes out of the box, including a theme named "liferay" which is based on the standard Liferay classic theme in blue.

Custom themes are created by writing CSS.  Sounds pretty simple, but can be quite complex.  Every widget has it's own classes automatically added to them, and the components can have classes added to them in the Java code (components have an addStyleName() method to add a CSS class to the component, yes I know it's misnamed, but I think they were trying to avoid confusion with Java classes).

Add-Ons

Vaadin Add-Ons are supplemental widgets that can be added to a Vaadin application to add new widgets that can be used in the application.  For example, there are Add-Ons to provide integration with charting packages, new layouts, extended core widgets that provide additional functionality, etc.

When an Add-On is added to a Vaadin application, the widgetset must be recompiled to create the complete widgetset for the application.  If the widgetset is not recompiled, the server side will have the code for the component (so you the developer can create, configure, and add the component), but the client side will not be able to render the widget.

Add-Ons can be found in the Vaadin Add-On Directory.

Vaadin in Liferay

The Vaadin website covers Vaadin as servlets in great detail, and touches on Vaadin portlets somewhat, but there are some things about using Vaadin in Liferay that are important to keep in mind...

The Widgetset

Vaadin portlets use a single, shared widgetset.  This widgetset is normally com.vaadin.portal.gwt.PortalDefaultWidgetSet, but it can be changed by setting the "vaadin.widgetset" property in portal-ext.properties.

The single widgetset is used by all Vaadin portlets deployed in the portal, so the widgetset must contain all of the Add-Ons used by any single Vaadin portlet.  Have a single Vaadin portlet that uses, say, the Refresher Add-On?  It must be in the widgetset for all portlets.

The Theme

Vaadin portlets will, by default, use a single, shared theme.  This is actually a good thing because it will make your Vaadin portlets look consistent across the portal.

The default portal theme is "liferay", but it can be changed by setting the "vaadin.theme" property in portal-ext.properties.

The Add-Ons

Add-Ons must be deployed into Liferay's WEB-INF/lib directory.  This is the only directory that will be used to compile the widgetset (details coming shortly), so this is where they must go. Vaadin portlets that use the Add-On(s) will use the liferay-plugin-package.properties file to define a dependency on the portal's jar.

The Resources

The compiled widgetset and the theme files represent all of the static files (resources) that Vaadin portlets will be using.  These files are always part of the Liferay ROOT web application, and will normally be available as /html/VAADIN/...  Vaadin will automatically be looking for the VAADIN directory to get the static resources, and this directory is found in the "/html" path, but this can be changed by setting the "vaadin.resources.path" property in portal-ext.properties.  NOTE: The resources path must be part of the ROOT application and must be in an accessible path for the client browser, as the browser will be submitting HTTP requests to get the static resources.

Vaadin Control Panel

All Liferay instances that will be using Vaadin in their portlets must add the Vaadin Control Panel.  It's not included in Liferay by default, but your ability to leverage Vaadin in the portal will be severely limited without it.

There are two key functions that the Vaadin Control Panel provides:

• The ability to change Vaadin versions on the fly.
• The ability to compile the portal's single, shared widgetset.

The Vaadin Control Panel for Liferay is a portlet that provides a new control panel for Vaadin.  It can be downloaded from the Add-On directory here.

Download the portlet and drop it into the deploy directory, and Liferay should deploy it.  Note that the control panel portlet does not adhere to Liferay's packaging requirements (it's missing the crucial liferay-plugin-package.properties file), so it may complain about it during deployment, but should still be functional.  You may or may not need to restart your application container post-deployment (I have seen it deploy successfully and be available, but also have seen cases where a restart is necessary).

When you go to the control panel, you'll have a new entry at the bottom of the Portal section named "Vaadin".

The interface is rather simplistic:

The first thing to notice is the "Change Version" link at the top of the file.  Liferay by default comes with a fairly old version of Vaadin.  You're going to want to change your version of Vaadin in the portal to the latest version as soon as possible.

The next thing to notice is the "Select Add-ons" checkboxes.  When you download an Add-On, you'll have a jar file that contains the Add-On code.  The jar file must be put into Liferay's WEB-INF/lib directory.  You can see the path where the jar file must go in the filesystem.

The checkboxes here allow you to select and deselect Add-Ons that will be included in the widgetset compile.

The last thing to notice is the "Compile Widget Set" button.  When you change the Vaadin version or when you enable/disable Vaadin Add-Ons, you MUST recompile the widgetset using this button.  Failure to do so will result in errors on the client side.

When you hit the "Compile Widget Set" button, a bunch of stuff will scroll in the "Output Console" section of the window.  This is the output of the GWT widgetset compiler.  In most cases you should get a successful result at the end of the compile.  If you get errors in the window, I would search the Vaadin forums for a match or try posting to the Vaadin or Liferay forums.

Issues Upgrading Vaadin in Liferay

The Vaadin Control Panel makes changing Vaadin versions really easy, but it does not handle the upgrade completely...

The Vaadin Control Panel only changes the version of the vaadin.jar in Liferay, but does not deal with the Vaadin themes.  Vaadin themes are released for each Vaadin release, and the themes contain bug fixes also.

Vaadin provides a special download for Liferay users, the Vaadin 6 Liferay Update Package.  This download will include the precompiled widgetsets (that you won't use since you're compiling your widgetset using the Vaadin Control Panel) and the updated themes.  You'll want to extract the themes directory from the download and copy it up to the Vaadin resources directory (default would be ROOT/html/VAADIN directory).  I actually deploy this locally using a JSP hook plugin (create a JSP hook plugin, put the new themes directory in the hook plugin, build and deploy to let Liferay handle the updating of the ROOT webapp).

Conclusion

Well, that about covers administrating Vaadin in Liferay.  My next blog post will cover developing Vaadin portlets...