Vaadin Liferay Development...

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...

 

[Jack Bakker]

Great intro David ; theme coordination across Vaadin and Liferay is interesting.. I have looked at Chameleon but have instead gone the distance to reference Vaadin style classes in Liferay themes in order to put styling in the hands of a 'common' theme developer.

[David H Nebinger]

Themes have, at least for me, proven to be the biggest pain in using Vaadin. Because of the Vaadin CSS classes, the Liferay themes are not usable. And it is not so easy to map from existing Liferay themes into a Vaadin theme either.

I ended up maintaining two separate themes, a Liferay theme (for styling the overall portal) and a Vaadin theme (for styling Vaadin).

[Jack Bakker]

Vaadin is still a bit of an island available to live within Liferay. A very attractive island in my view and I use it much as you do. Very cool. If the island is to be welcomed even more into the Liferay fold, there is the theme challenge, mixing with Liferay searchcontainers, etc. that need consideration. Also when it comes to responsive layouts, I would rather do MVCPortlet than Vaadin. Side comment: I really 'dig' Struts2. Side comment: there is also developer expertise available.

Sooo many php developers, but .. less MVCPortlet developers and even less Vaadin - though I am with you, Vaadin (leveraging GWT) in Liferay is awesome. Dare I say cool yet again.

[David H Nebinger]

You're absolutely right about Vaadin being an island. That's why I'm going to blog about it and hopefully get the word out to expand the usage base. I think the shortage of Vaadin resources is certainly true here in the US, but I believe there is a bigger base in Europe.

Vaadin does have their TouchKit extension to support mobile development... Responsive layouts are one thing, but getting mobile touch enhancements within a portlet might be worth it...

[Jeffrey Handa]

Great post. Thanks for sharing your experience and I am looking forward to the post on development!

[Nono Carballo]

Have you tried Vaadin 7 for portlet development?

[Nono Carballo]

Have you tried Vaadin 7 for portlet development?

[Nono Carballo]

Have you tried Vaadin 7 for portlet development?

[Nono Carballo]

Have you tried Vaadin 7 for portlet development?

[David H Nebinger]

Yes, but it does have a few bugs (the biggest one I found is that setting a height of 100% causes the widgets not to be rendered).

Requires a new control panel that is compatible with Vaadin 7. There was a RC of one created for Vaadin, and I actually have one that I've been working on for putting into the LR marketplace, but I've been waiting for 7.1 to stabilize so I can test 7.1 compatibility. The control panel has special security needs, so at this point it cannot go to the marketplace until 6.2 is released...

[Nono Carballo]

Thanks David, I wanted to try Vaadin for portlet development, but after read your comment, I´ll wait to the next version.

[David H Nebinger]

No need to wait. Vaadin 6 is very powerful and stable and works quite well. We have been very pleased with it, and leverage V6 and the V6 addons successfully.

[Nono Carballo]

Ok, thanks David, I´ll start with Vaadin 6, but will I have troubles when migration to Vaadin 7?

[David H Nebinger]

There's some significant underlying changes between V6 and V7, so there is some migration from V6 to V7. But if you're fully versed in V6 you'll find the changes easy to do when it comes time to...

[Nono Carballo]

Thanks David.

[Ivano Carrara]

Hi all,

Please, why all people are talking about the beauty of Liferay and Vaadin togheter, and no one man in the world wrote a clear and simple example to build a CRUD portlet for Liferay using Vaadin and data persistence managed by Liferay's service layer ?

Why no one is able to show and example using Vaadin user interface and services classes generated by Liferay's Service Builder ?

Thank you for any comments on this !

Ivano C.

[David H Nebinger]

Vaadin is a great framework for building a responsive portlet application, but it doesn't negate the need to leverage existing Liferay knowledge to build applications. CRUD portlets are 1/2 SB implementation in LR and 1/2 user interface developed in Vaadin. There's no magic involved, you create a form in Vaadin w/ a "Save" button, then on the ClickListener of the button, you add the Liferay API calls to create and add the entity to the database. You can add verification/validation logic either at the field level (set immediate to true to validate on the fly) or at the form level (as part of your ClickListener implementation).

I have created many CRUD portlets leveraging Vaadin and SB. There's nothing magical or difficult to them, they just aren't really that interesting.

[Ivano Carrara]

Hi David, thank you for your reply ...

I think that the most interesting example can be how Vaadin can manage a complete example, starting from load and list the Liferay's users table (the same as Liferay's Search Container), then how to manage the edit and delete of elements, then how to manage the insert of a new User.

I'm sure that no one published a project using Vaadin equivalent of a portlet listing data based on Liferay's Search Container then edit/delete/insert operations

Still, the strange thing is that many men told they wrote CRUD portlets but no one publish a simple example on that ...

I mean that no one published Java code, only long explanatons, but no code.

Thank you in advance for comments ...

Ivano C.

[David H Nebinger]

Normally I try not to muddy the waters... If you have something you're doing through Liferay tools such as search or user administration, it's usually better off leaving the work to those tools.

That said, adding a user is done through the UserLocalServiceUtil.addUser() method. For the Vaadin side, you would create your form or forms to collect all of the information needed to pass through to the call.

So the interesting stuff on the Vaadin side would be, for example, validating an email address. You can set the email field to immediate, then add a ValueChangedListener to it. Inside of your listener implementation, you get the value of the email field and then you can use UserLocalServiceUtil.fetchUserByEmailAddress() to see if there's already a user registered with that address, then you can display a notification or something so the user has to go and fix the email address...

That's why I said it's not very interesting. You're presenting a form, you validate and verify user has entered into the form, and then you invoke the appropriate Liferay API to persist the data.

Even in the case of adding a User, it just tends not to be very interesting although it is completely doable.

But I do see your point in that more examples would be nice. I'm a little busy this week, but I'll try to get an example posted up here this coming weekend. Hopefully that will work for you?

Also I'll be at the Liferay Symposium in Boston coming up in October; if you're going to be around, please look me up and we can talk Vaadin over a beer or something

[Ivano Carrara]

Dear David, you are so gentle and your frequent posts in Liferay's' forum and blog are very useful...

Thank you also for your actual effort to explain me ...

I think that the real critical point is about how to load some thousand of records from a Liferay's managed database into a pagination control of Vaadin... It loads all records in memory and after a few users do the same I think the memory is full.

I know that there is a Lazy loader control to do that but no one explained how to link data returned from some sort of MyEntityLocalServiceUtil.getAllRecords(...) to a Vaadin control to paginate the data ...

I hope to read soon a new post from you about this secret !! :-)

Thank you in advance for your valuable support ...

Ivano C.

[David H Nebinger]

Ah, now paged results is a black art...

So Vaadin has support for paged retrievals using direct JDBC, but there is no support for paged results using Liferay's methods.

In general I try to avoid Vaadin's natural table handling because, like you pointed out, it is quite easy to exhaust server side resources when users are viewing tables with large row counts.

Instead I tend to fall back to manually handling pagination. You can leverage Liferay's APIs (most list methods from Liferay have a corresponding windowed version to grab a subset of rows). You can grab the row count, handle moving forwards and backwards, all without the pitfalls of oversized table handling.

Now if I absolutely had to support in in Liferay, I'd extend SQLContainer and override methods that access JDBC to use the corresponding Liferay API to get the total row count and retrieve records, By extending SQLContainer, you can leverage the examples from the Book of Vaadin that demonstrate how to use SQLContainer.

[Jack Bakker]

I see two mind the gaps when using Vaadin in Liferay: 1) reducing overhead for larger datasets with many users (in Table component for example) 2) coordinating Liferay and Vaadin themes. A good CRUD example might address these.

[David H Nebinger]

#1 is handled by manually paging the records. UserLocalServiceUtil, for example, has getUsersCount() method to get the number of users, and getUsers(int start, int end) grabs a subset of those users. Many of the Liferay APIs support similar things. For your own custom entities, the persistence classes always has paging methods, you just need to expose them in EntityLocalServiceImpl. So you manually support paging the dataset, each page forward increases your start/end values by the number of records you display, ... It is not elegant, but it does the trick and limits the server side overhead/impact.

#2, well there is no coordination. In Vaadin you have to create your vaadin theme, and often times you have to undo what Liferay styles the default tags with. Vaadin uses it's own classes for styling, so you have to style the vaadin classes in a separate Vaadin theme. Unfortunately this means you create a Liferay theme for styling your site, then you have to recreate the theme as a Vaadin theme bringing your colors, etc. over to the Vaadin theme. Yes, this is ugly, but there is no other choice.

[Ivano Carrara]

#1 No, I think that the best solution is to use Lazy Query Container Vaadin add on.
The QueryFactory and Query interface implementations are designed to be application specific and should invoke a data source like WebService client, JDBC connection, JPA context or Java service class to read and write data items. The data source has to support querying data in batches.

#2 I hope the Valo Vaadin Theme can help us.

At the end, I hope that some Liferay and Vaadin people can help us to understand the beauty of their products !

Thank you for your comments ...

Ivano C.

[David Nebinger]

Lazy query container works, and I've posted a response to your forum thread about usage. I do worry though about server side impact of caching many records by many simultaneous users. I guess it takes an understanding of your environment and users to determine if it will be an impact or not.

Valo is not going to be much of a help... It is a responsive theme design for Vaadin, but it still has the same issues the other themes have, namely their own custom class names and expectation that there is no underlying theme to build from. You'll still end up creating a custom theme (or perhaps a concept of a valo color scheme or something, I haven't figured out how they handle the color scheme changes) to bring consistency to both your Liferay environment and Vaadin portlets.