Creating a Liferay Marketing Theme

General Blogs May 22, 2015 By David H Nebinger


So I'm not the best theme person around.  I'm less a UI guy and more of an implementation person.  Honestly I hate working on themes.  Maybe it's just me, but all of the styling work that you have to do in Liferay, well honestly I find it quite daunting.

And when you throw in Bootstrap for responsiveness, SASS for "simplified" stylesheets, FontAwesome, etc., well for me things just go from bad to worse.

I have my head down in the core all day, why would I want to step out of that clean, organized world (wink) to dip my toes into (what I consider) the mess that is theming?

Well, there's no use complaining about it.  I need a theme for a custom personal site I'm working on.  I envison a main page kind of like what is using and support pages that will probably adhere to more of a classic sort of flavor for child pages.  The main page, for a developer, well that will feel pretty worthless, but it's just one of those things that everyone needs these days and I'm itching for a learning experience, so this blog entry is going to follow my effort for creating such a theme in Liferay.

I'm not alone in this kind of need.  Recently my friend Jack Bakker posted in the forum how to put together a theme like the one Liferay has for and the wordpress-like theme on the child pages such as

So since I was creating a similar theme, I thought I'd capture the how-to about it and include it here in a new blog post.

Starting Point

So along with not being a theme person, well I'm not much of an artist.  I can look at web sites and identify things I like and things I don't like, but if you ask me to create a "standard" marketing page I would spend days scratching out ideas and probably come up empty.

So what I needed was a starting point.  Somewhere that I could grab a workable theme idea.  Something that had the marketing-like concept from the North America Symposium site but where I wasn't really stealing their work.

I remembered a story recently on Slashdot that pointed to a site created by a couple of college students that would generate mock startup websites.  The images, etc are all covered by the Creative Commons, so I figure I can borrow from them since I'm more than willing to give appropriate attributions.

So the site is and each time you click on it you should get a completely fresh website.  Do it a couple of times and you'll see familiar patterns on the pages, from a single image which stays permanently in place while the scrollable area slides over it, a consistent color palette based on image colors, responsive layout based on Bootstrap, leverages FontAwesome, etc.  Basically everything that I'm looking to implement.  Since the site is not based on Liferay, I'm just effectively using the CC images and concepts from their site, but like I said all real credit for the look and feel I give to them.

I flipped through a couple of times in Firefox until I found a basic color palette and background image that would work.  I used Firefox's save feature to save the complete web page so I got images, css, and the main page.

I'm sure you're wondering why I'm spending a lot of time explaining how I came up with the starting theme.  It's not really my goal to show everyone how to grab someone else's ideas.

But for many of you developers out there, I'm now at the point where you will be when some whiz-bang UI developer comes to your cube with a zip file full of her excellent UI designs in simple HTML, CSS, JS and imagery and they say "Here you go, now make Liferay look like this..."

That's hopefully what we'll get out of this blog, a fancy front page theme for Liferay to impress your coworkers and bosses.

Creating the Projects

So we're actually going to be creating three different projects - two theme projects and one layouttpl project.  One theme project will cover the main page and the second theme will provide the wordpressy-like child page themes.  The layouttpl project will allow us to define the separate zones that will exist in the pages and allow the themes to define how the zones will look.

Wanting to leave the IDE out of the picture, we can create our theme projects using "mvn archetype:generate".  Use the "liferay-theme-archetype" to create a new theme projects and give them relevant values.  Use the "liferay-layouttpl-archetype" to create a new layout template project and give it the relevant values.

New theme projects use "_styled" as the parent theme in the pom.xml file; that's a good enough starting place for our front page since most other themes would be overkill for what we're doing.

If you're using the SDK, you should do an initial project build of the themes right off.  This will pull in the theme files from the _styled theme so you just have to create the _diffs folders and start adding your override files.  For Maven developers, you can just start adding your overrides to the src/main/webapp folders and when you build the projects, Maven will take care of merging the files.

I'm using Maven for these projects (as I'm doing for all of my projects these days), so if you're using the SDK you'll have to modify the instructions appropriatiately.  I would recommend that you get off of the SDK as soon as you can since that's the apparent direction Liferay is giving us.

The themes that I'm creating have CSS, images, JS and, of course, their own Velocity templates, so we should create the src/main/webapp/css, src/main/webapp/images, src/main/webapp/js and src/main/webapp/templates folders where our files will go.

Images are further divided by type.  The marketing theme I'm using really only needs the background image (I'm not going to be using the face images), but I'll put it in a src/main/webapp/images/theme folder (use your theme project as the folder name) to keep it (and possibly others) separate from regular theme images.

The layout template project is pretty much ready to start editing right away, so we'll actually tackle that first.

Creating the Layout Template

The layout template is really important for the marketing type themes.  These themes typically take up 100% of the width of the browser (I love that) and a bunch of different rows each styled differently.

From, we see 7 different rows that contain different content: Hero, Quote, Why, Quote, Team, Quote, Sponsors and Footer.  There's also the header (with navigation).  Most of the rows are a single column, but the Why and Team sections are actually 3 column.

We'll mimic the same layout and use as our row types: hero, quote, why, team, sponsors and footer.  These are going to be the basis for our classes for the sections of the layout.  Our final layout is going to be, in Liferay naming venacular, 1-1-3-1-3-1-1-1  cheeky

Here's the content for our marketing layout template file:

<div class="full-screen-layout" id="main-content" role="main">
    <div class="portlet-layout row-fluid vol-hero">
        <div class="portlet-column portlet-column-only span12" id="column-1">
            $processor.processColumn("column-1", "portlet-column-content portlet-column-content-only")
    <div class="portlet-layout row-fluid vol-quote">
        <div class="portlet-column portlet-column-only span12" id="column-2">
            $processor.processColumn("column-2", "portlet-column-content portlet-column-content-only")
    <div class="portlet-layout row-fluid vol-why">
        <div class="portlet-column portlet-column-first span4" id="column-3">
            $processor.processColumn("column-3", "portlet-column-content portlet-column-content-first")

        <div class="portlet-column span4" id="column-4">
            $processor.processColumn("column-4", "portlet-column-content")

        <div class="portlet-column portlet-column-last span4" id="column-5">
            $processor.processColumn("column-5", "portlet-column-content portlet-column-content-last")
    <div class="portlet-layout row-fluid vol-quote">
        <div class="portlet-column portlet-column-only span12" id="column-6">
            $processor.processColumn("column-6", "portlet-column-content portlet-column-content-only")
    <div class="portlet-layout row-fluid vol-team">
        <div class="portlet-column portlet-column-first span4" id="column-7">
            $processor.processColumn("column-7", "portlet-column-content portlet-column-content-first")

        <div class="portlet-column span4" id="column-8">
            $processor.processColumn("column-8", "portlet-column-content")

        <div class="portlet-column portlet-column-last span4" id="column-9">
            $processor.processColumn("column-9", "portlet-column-content portlet-column-content-last")
    <div class="portlet-layout row-fluid vol-quote">
        <div class="portlet-column portlet-column-only span12" id="column-10">
            $processor.processColumn("column-10", "portlet-column-content portlet-column-content-only")
    <div class="portlet-layout row-fluid vol-sponsors">
        <div class="portlet-column portlet-column-only span12" id="column-11">
            $processor.processColumn("column-11", "portlet-column-content portlet-column-content-only")
    <div class="portlet-layout row-fluid vol-footer">
        <div class="portlet-column portlet-column-only span12" id="column-12">
            $processor.processColumn("column-12", "portlet-column-content portlet-column-content-only")

This defines our layout (I've already copied to the wap template so they both match).  The important aspect to notice here is the addition of classes to the divs for the separate rows.  I've prefixed my classes with "vol-" to avoid namespace conflicts, but otherwise you'll see I've used the types that we picked out earlier.

For the child pages such as Why Attend, well this page has specific theming support but uses a standard 1 column layout template, so we don't need a custom template here.

Layout templates are fairly easy to create, but they're just as easy to build, deploy and test.  Build your layout template project and deploy it to your portal (verifying deployment is completed without error).  Now you should be able to log in and use the layout template to test the results.

Using the classic theme and your new layout, you can drop web content displays into each area (Classic gives you a big drop zone for each column).  Here's what I got when I did it locally:

Not very flashy for certain, but it does give you an idea of where we're headed.

Building the Marketing Theme

Next we'll start on the marketing theme.  I'm not really going to get into the CSS stuff myself, I managed to get it all working and frankly this is a Liferay site, not a CSS site, so we'll leave you to find some other source for the CSS details.

I do want to highlight some of the important parts, though, the ones that make the theme work.


So there's two basic forms that the navigation menu take.  The first, such as the one on, has the navigation at the top of the page above the hero image.  The second, such as the one on the 2015 Symposium, has the hero image above the navigation.

The first case is the close to the classic Liferay navigation found in many themes, even classic.  The big difference would be the absence of the big company image in the upper left corner, now there's typically a much smaller image (sized per the nav area) that is part of and to the left of the navigation on the right.  For this implementation, you're really going to be tweaking the portal_normal.vm file to get rid of the big company logo above navigation in lieu of a smaller image that is integrated right into the navigation bar.  You can still stick with Liferay's use of the dynamic company logos as long as you keep em small or something that will scale correctly to the nav bar size.  The rest is just a little bit of HTML and CSS magic to get it to work.

The second option with the hero above the navigation, well that one is a little more interesting.  In this case it's a heck of a lot easier if you can just build your hero stuff right into portal_normal.vm to appear above the normal navigation area.  The 2015 Symposium uses this technique to lay out all the hero image above where the navigation fits in.  What makes this so easy is that you can then stick the nav bar to the top of the page as you scroll and you don't have to worry about embedding a dynamic journal article in the header.  Makes the theme specific for your particular need (i.e. the 2015 Symposium theme can only be used for the 2015 Symposium, you'd have to create a new theme for the 2016 Symposium).

Alternatively you could try to use a dynamic hero section in the content area then use funky CSS and JS tricks to manipulate the dom and get it above the nav bar.  It might allow you to use a dynamic hero, but honestly I'd be reluctant to go down this road because it just seems to fragile to me.  I think you'd always be worried about how to get it to work on all past, present and future browsers, mobile, etc.  I cannot say it's not possible cuz I'm sure it is, I guess I'm saying that you'd probably burn through too much time, money and resources just getting it to work and keeping it working.

For my implementation, I'm going with the first version, the nav bar at the top of the page above the content area.  So my portal_normal.vm file starts like this:

<header id="banner" role="banner">
	#if ($has_navigation || $is_signed_in)
		#parse ("$full_templates_path/navigation.vm")

Wait, where's the logo?  Where's the sign in link stuff?  Well, like I said, my implementation now has those items embedded within the nav bar.  So I've moved them into navigation.vm.  Basically the logo stuff is right before the <ul> tag for navigation and the sign in link stuff is next after the closing </ul> tag.  Since I'm trying to mimic a marketing page that has greatly simplified the menus, I've taken out the second level navigation stuff too.  Note that to mimic the marketing sites that have menus with links to anchors in the page, just add initial static links as <li /> items in the nav bar just before the normal velocity processing for pages.  You may even choose to exclude the regular nav logic altogether moving it instead to, say, a hamburger menu.  The choice is yours.

Without any styling applied, the top of our page now looks like:

Not significantly different, but we have the basis for our actual nav bar.  All we need to do is apply styles to the appropriate elements and we'll be good to go.

The Hero

So the hero, for those that don't know, is that big worthless image at the top of most marketing sites that have no practical purpose but to show some sort of artwork but mostly it will include happy faces of people you're supposed to think really like the products of the company they're on, but most of the time they are just stock images purchased for use on the page.  Hmm, I wonder if that statement will come across as a bit cynical?

The hero image these days is usually placed as a background image.  Sometimes they stay at the top of the page, but the latest trend is to keep the image at the top of the browser window and let the page content scroll overtop of it, often with one transparent box that scrolls over the window and the rest are opaque and hide the background as the user scrolls down in the page.

My implementation is going to use a similarly placed background image that will be at the top of the browser window and will not scroll.  However, the vol-hero row should be transparent so the background shows through and the content of the hero row will scroll over the image.

So how exactly are we going to build this piece?  Well, it's actually pretty simple.  So first I got my background image and added it to the theme.  The full path for the image is /vol-theme/images/vol/metaldeer.jpg.  I deployed my theme so it would be available.

The rest is done within a web content display.  In the web content display for the vol-hero column, I used the following web content:

<div id="hero-007">
  <p style="text-align: center;"><span style="font-size:24px;"><span style="color:#FFFFFF;">This is the hero page.</span></span></p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;">&nbsp;</p>
  <p style="text-align: center;"><span style="font-size:24px;"><span style="color:#FFFFFF;">It is quite large.</span></span></p>
  <p style="text-align: center;">&nbsp;</p>

Pretty simple, but I want to highlight the div which surrounds the content - hero-007.

That's important because we're going to use that for applying the styling.  Here's the rule that was used in custom.css in the theme:

#hero-007 {
    background: url(../images/vol/metaldeer.jpg);
    background-position: top center;
    background-repeat: no-repeat;
    background-attachment: fixed;
    background-size: cover;
    min-height: 500px;

If you didn't want to embed this in the theme, another option is to use advanced styling under the look and feel for the web content display portlet.  Load your background image into Docs and Media and get the link to it, that would be the URL to use, otherwise this rule can be used as-is.

Here's how it looks:

Since the background is positioned at the top center and has attachement fixed, it will stay in place as you scroll the page.  Since the lower rows in our layout don't have the background, the image is just the background for the hero area.

A quick note about opacity...  There are some CSS things and JS things you can do to tweak the opacity of the background image.  My big question is simply "why?"  I mean, unless you don't have an image tool on your computer and/or you don't have direct access to the image there's simply no reason not to tweak the image for the right opacity and use that image.  The upside is it will work on all browsers and versions, including mobile, and it won't suffer the fragility of a CSS/JS solution.


After seeing the floating background for the hero, tackling the quote sections will be a breeze.  Here we're going to add a class to our theme for the background and the text styling and we'll use a simple web content display area.  The CSS is both long and boring, so it's left out of the blog, but here's how it looks so far:

Note the cool addition of FontAwesome quotes in here, I didn't have to do a thing but reference it in the web content.

There are two options to get the Font Awesome images, the easiest is to output HTML like <i class="icon-left-quote"></i> and the _styled theme actually took care of the rest.  To see the available images in Liferay 6.2, I went to Nick Piesco's Alloy UI Font Awesome Cheat Sheet.  The other option is to use a content style to set the code for the Font Awesome glyph, although the problem you have here is that some codes from FA do not work because of Liferay's own version.

Note that I am perturbed that I can't use normal Font Awesome classes and that Alloy has to have their own implementation because, of course, it's already out of date and even if they shipped an update tomorrow it would probably be out of date the day after. 

The quote itself is really not very special.  It's a <blockquote /> tag with a two-line right-justified <h2 /> underneath.  The blockquote has styles applied to it from the theme:

blockquote:before, .aui blockquote:before {
    top: -20px;
    left: -10px;
    content: "\201C";
blockquote:after, .aui blockquote:after {
    top: -20px;
    right: 5%;
    content: "\201D";

The important part is the content style, the two codes given are for the left and right quotes respectively.

The Why

So the why row is labeled as such because it supposedly answers the question "Why Us" and has 3 boxes to drop quick imagery that provide the top 3 reasons.  I don't really have reasons, but I will fill in the boxes to see how it looks...

These FontAwesome guys are created by using a div that is styled with a background color circle and an <i class="icon-beer"></i> HTML code (different values for the other icons) to overlay the FontAwesome images.  Again these come from Nick Piesco's Cheat Sheet so any of the listed icon types will work for 6.2.

When laying this out I realized that I wanted a simple header for the 3 cells so I inserted a one-column row above the previous vol-team row in the layout above and dropped this web content in.

The others are basically 3 different web content displays dropped in each of the cells.  Yes, the icons are not centered very well, but that is something that you would fix when tweaking the output.


Sure, the theme is not done, but at this point I think it's clear that I'm just going to keep adding content into web content displays and providing some stuff in the theme to style it the way it should look, to make it the way I want.

I hope, at this point, that it's clear that although some aspects of Liferay theming can be daunting, creating a Marketing theme is not really too difficult.  Trust me, as I said earlier I am not a strong CSS person so if I can do this, you can do it too.

So what's next?  Well, the theme is not very responsive.  I tried shrinking the page and it didn't do what I want so I'm going to look into that.  And I don't like the old dockbar look you get from the _styled theme so I'm going to pull in the classic dockbar.  Finally the nav bar is not sticking at the top of the page when I scroll, so I'll have to flush out the javascript to flip the classes and keep it in place.

Who knows, maybe one or more of these will make it into a future blog post...  wink

Fake ServiceBuilder Entities

General Blogs May 21, 2015 By David H Nebinger


So this is a concept that comes up from time to time on the forums - How do I return a non-database complex object from my ServiceBuilder-generated service layer?

The common answer is usually to bundle the class(es) defining the complex objects into a jar and deploy the jar to the global class loader.  This is a workable solution, but as with all global jars it can only be updated when the app container is shut down.  When organizations go this route, most of the time the simple global jar with model classes tends to grow into a monstrosity jar with the model classes, service classes for dealing with the model classes, etc.  They naturally grow to an unweildy size that require a lot of maintenance and deployment activity.  This leads to runtime issues where each consumer of the business logic classes in the global jar are actually instantiating their own instances in their own web applications so there's multiple runtime objects and no "shared" instance access.

So what starts as a seemingly simple solution can actually get bogged down over time.

An alternate solution that was initially outlined in this forum thread centers around what I call, for lack of a snazzier name, Fake Entities.

What Is a Fake Entity?

So what is a Fake Entity really?  Well it is exactly like a regular ServiceBuilder entity minus the backing database table.  Since it is like a ServiceBuilder entity, though, there's a lot of functionality you get:

  • Local interfaces for working with the entities.
  • Remote interfaces for accessing with regular web services.
  • With the remote interfaces you can layer in security checks to manage access.
  • Since the fake entities are managed by a ServiceBuilder implementation, you have one service providing plugin exposing a single access point for business logic so there can be data and logic sharing by all service consumers.
  • There is reduced resource requirements portal-wide because there is a single instance of the service provider classes.
  • It can be easy/natural to add and use the entities alongside the regular database-backed entities (some restrictions apply wink).
  • Updates to the entity and the service layer are deployed just like any other ServiceBuilder plugin is deployed.

Basically any benefit you can name for a database-backed ServiceBuilder entity usage applies to the fake entities.

So now you're sold on using Fake Entities, and you probably want to know how to do so.

Defining a DataSource

Yes, we still need a DataSource.  ServiceBuilder is dependent upon a DataSource definition for the entity and, if one isn't given, Liferay will use it's own DataSource (and create tables in the Liferay database).  As we don't want to create database tables, we need an alternate DataSource.

From the forum thread, Remis Lima Baima suggests using Spring's org.springframework.jdbc.datasource.LazyConnectionDataSourceProxy as the DataSource.  The LazyConnectionDataSourceProxy is a DataSource implementation that will not connect to a database until a javax.jdbc.Statement object is created.  For our fake entity purposes, as long as we do not attempt to do anything w/ the database side (i.e. the persistence layer or the finders, etc.) it would work.  Obviously, though, the risk is that some developer may try to use the data tier w/o knowing they're fake entities and you have to deal w/ all of the database exceptions that would be thrown as a result of missing tables.

You could protect yourself from this by using an HSQL database connection to back the LazyConnectionDataSourceProxy.  That way if entities do get created they would be in a throwaway database.  The problem here is that eventually the developers might start using them as database entities (since they would work as if they were real database entities), so you become dependent upon a database that is not intended to necessarily be a production database source.

I like the recommendation from my good friend Jack Bakker.  Basically he created a utility class to use to define a DataSource factory that always returns a null DataSource: 

package com.example;

import javax.sql.DataSource;

 * class NoDataSource: A factory class to do nothing but return a null data source object.
 * @author Jack Bakker
public class NoDataSource {
	 * getDataSource: Supposed to return a DataSource.
	 * @return DataSource Always returns null.
	public static DataSource getDataSource() {	
		return null;

I think the brilliance of this idea is that if a developer tries to access the database portion for an entity, it's going to generate a NullPointerException.  While not very ellegant, it will leave little doubt that the database layer is off-limits.

Defining the ext-spring.xml Beans

To use your datasource, you have to have some additional beans defined in the META-INF/ext-spring.xml file for your ServiceBuilder project:


<?xml version="1.0"?>

<beans xmlns=""

	<bean id="noDataSource" class="com.example.NoDataSource" factory-method="getDataSource" />


So we're defining our factory class with the factory method to create a DataSource instance.

Note: On using this in an EE SP 11 environment I got a NullPointerException from com.liferay.portal.jsonwebservice.JSONWebServiceRegistrator.  Apparently this defines a bean named noDataSource correctly for runtime but not available loading as a bean which leads to the NPE.  There's currently a fix in the pipeline to deal with the null bean reference in the registrator, but in the mean time you can actually solve this by creating a "NullDataSource" class that implements javax.sql.DataSource.  In your methods, just return nulls for everything and you're good.  The bean would then become <bean id="noDataSource" class="com.example.NullDataSource" /> and the NPE will go away.

Defining the Entities in service.xml

Next we'll add the entity definitions in our service.xml file:


<!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 6.2.0//EN" "">

<service-builder package-path="com.dnebinger.liferay.fake">
	<!-- Define our first fake entity... -->
	<entity name="Foo" uuid="true" local-service="true" remote-service="true" data-source="noDataSource">

		<!-- Even though we're a fake entity, we still need to have one column as a primary key. -->

		<column name="fooId" type="long" primary="true" />

		<!-- Now we can add any other columns to our entity that we want. -->

		<column name="field1" type="String" />
		<column name="field2" type="boolean" />
		<column name="field3" type="int" />
		<column name="field4" type="Date" />
		<column name="field5" type="String" />
	<!-- Define our second fake entity -->
	<entity name="Point" local-service="true" remote-service="true" data-source="noDataSource">
		<column name="x" type="double" primary="true" />
		<column name="y" type="double" primary="true" />

The Foo entity is just a simple example of what you would do in your entity.  The Point entity represents a point on a cartesian plane.  We'll be using points to create a small library of geometric functions based on the Point.

Building Services

Before you can add methods to your implementation class, you need to build the services.  There's nothing special in our entities so building services in this case is a simple process.

It is during the building of services where you may encounter issues in your entity definitions.

One common error is leaving out a primary column.  Even though these entities will not be backed by a database, ServiceBuilder still requires that at least one column is identified as the primary column.  Doesn't matter which one(s) you use, but they will be part of the constructor for the instance.

Otherwise the same rules for database-backed entities enforced by ServiceBuilder are also apply to our fake entities.

Adding Business Methods

Building services gives us the initial service layer, although the default SB methods shouldn't be used (since we don't have a database) so they are not very helpful.  So let's add some methods to our new com.dnebinger.liferay.fake.service.impl.PointLocalServiceImpl class.

I hate exposing things outside of the service layer that I don't need to.  Since our Point has a compound key, the normal createPoint() method takes a PointPK instance.  Instead of requiring the service consumer to know about the PointPK class, I prefer to add a utility method that overloads the creation:

 * createPoint: Utility constructor to hide the PointPK class.
 * @param x
 * @param y
 * @return Point The newly constructed point.
public Point createPoint(double x, double y) {
	return createPoint(new PointPK(x,y));

Since these are fake entities, you might want to override the default methods to throw exceptions should some unknowing developer try to invoke the class:

 * @see com.dnebinger.liferay.fake.service.base.PointLocalServiceBaseImpl#addPoint(com.dnebinger.liferay.fake.model.Point)
public Point addPoint(Point point) throws SystemException {
	throw new SystemException("Points cannot be persisted.");

It's a lot of busywork to override all of the default methods, but it can save you some headaches in the future.

But we're really here to create some business classes.  I've added three simple methods to find the slope of a line, the distance of a line and calculate the area of a triangle formed by three points:

 * findSlope: Finds the slope of a line for two points, m = (y1 - y2) / (x1 - x2).
 * @param p1
 * @param p2
 * @return double The slope of the line.
public double findSlope(final Point p1, final Point p2) {
	final double m = (p1.getY() - p2.getY()) / (p1.getX() - p2.getX());

	return m;

 * findDistance: Finds the distance of a line formed by the two points, uses the distance formula, d = sqrt((x2 - x1)^2 + (y2 - y1)^2).
 * @param p1
 * @param p2
 * @return double The distance of the line.
public double findDistance(final Point p1, final Point p2) {
	final double x2 = Math.pow((p2.getX() - p1.getX()), 2);
	final double y2 = Math.pow((p2.getY() - p1.getY()), 2);

	final double d = Math.sqrt(x2 + y2);

	return d;

 * findArea: Finds the area of a triangle formed by the three points using Heron's formula:
 * @param p1
 * @param p2
 * @param p3
 * @return
public double findArea(final Point p1, final Point p2, final Point p3) {
	// we actually need the lengths of the three sides...
	final double a = findDistance(p1, p2);
	final double b = findDistance(p2, p3);
	final double c = findDistance(p3, p1);

	// you also need the value for s
	final double s = 0.5 * (a + b + c);

	// and then you can calculate the area.
	final double area = Math.sqrt(s * (s - a) * (s - b) * (s - c));

	return area;

Not very useful or exciting, but it is just meant to demonstrate how we can build a library of functions around our fake entities.

We could also create a singleton instance of point that is available to all service consumers:

 * cachedPoint: A shared point that will be visible across every service consumer.
protected Point cachedPoint = null;
 * getCachedPoint: Returns the cached point.
 * @return Point The cached point.
public Point getCachedPoint() {
	return cachedPoint;
 * setCachedPoint: Sets the cached point.
 * @param p
public void setCachedPoint(final Point p) {
	cachedPoint = p;

Build Services Again

Since we've added methods to our PointLocalServiceImpl class, we have to build services again to add them to the service jar.

We can then use the service jar in other Liferay plugins to access the shared service tier.


So I've introduced fake entities and showed you how to create them, but you may still be wondering how they may apply to you.

The answer comes down to the real reason for ServiceBuilder's existence.  No, ServiceBuilder is not just a broken ORM or anything that you may have heard or thought on your own.

ServiceBuilder's raison d'etre is to provide a service layer that can be shared with many service consumers even across the web application container's class loader boundary.

I may get some pushback on this, but trust me it's the best way to think of ServiceBuilder.  It explains why it is a crippled ORM, why it is normal to include business logic in the service implementation, why it has built-in support for web services and JSON.  It explains why there is one plugin that is providing the service and multiple copies of the service jar floating in the environment with a thin API to access the shared service layer.

When you see ServiceBuilder in this light, it becomes clear that you will want to use entities for a lot more than just your database classes.

Have a set of web services that multiple portlet projects will need to invoke?  If you wrap them in a ServiceBuilder implementation, those portlets only need a service jar.  Your implementation classes can hide all of the details in creating and using the web service client.  For changes to the web service, well you just need to make a change to your service provider, the service consumers can remain unchanged (assuming you don't need some sort of API change).

Have a non-database resource that multiple portlet projects will need to read/write?  If you wrap them in a ServiceBuilder implementation, the service consumers can share access to the resource.  Service consumer A can write something to the resource and the other service consumers can read the value back.  The service provider can choose to cache the changes (if updating the resource is a time-intensive process) and since the service consumers are pulling from the service provider the cached value(s) can be returned.

Building a complex library of business logic to be shared with multiple plugins?  If you wrap it in a ServiceBuilder implementation, you get all of the benefits of using a shared implementation w/o runtime implications of multiple instanciated objects.

Have a Hibernate or JPA data access layer you need to use in multiple plugins?  If you try to copy the code to the separate plugins, they all need their own database connections, their own ehcaches, etc.  If you wrap this in a ServiceBuilder implementation, the service provider becomes a proxy to your data access layer implementation.  Service consumers leverage the service jar to access the service provider; the service provider is the only plugin that requires the database connection, the ehcache, etc.  Since the service consumers are all going through the same instance, issues with stale caches and dirty reads/writes disappear.

All of these things become possible in ServiceBuilder with the introduction of the Fake Entity.

Vaadin Pro Tools and Liferay

General Blogs May 5, 2015 By David H Nebinger

So Vaadin has a complete set of basic widgets (checkboxes, input fields, comboboxes, etc.) and some advanced controls (date picker, menu bar, table, etc.).

They also have the Add-On directory which contains a slew of professional and user contributed widgets (some of my favorites are the masked text fields).

But Vaadin also has the Pro Tools - snazzy widgets with a lot of capabilities, but at a cost.  These widgets aren't free, but they are certainly not outrageous even for small shops or projects.

About Vaadin Pro Tools

There are currently four Pro Tools available:

  • Charts
  • Spreadsheet
  • TestBench
  • TouchKit

Charts is a charting package that combines Vaadin and HighCharts to deliver a responsive charting package that allows for a lot of interaction possibilities between a browser-based chart and server-side logic and data access.

Spreadsheet is just what it sounds like, it's an implementation of a spreadsheet widget that runs right in the browser complete with support for functions, editing, etc.

TestBench is an extension for JUnit which allows for UI validation from a CI perspective.  Rather than requiring a set of eyeballs to review the visual changes in a build, TestBench can use screen caps to compare and identify changes that are inconsistent or unexpected.

TouchKit is a framework for building mobile-compatible Vaadin applications.  A fresh spin on the "write once, run anywhere" concept, TouchKit allows Vaadin applications to act as native mobile apps even though they are still web-based.

Liferay and Pro Tools

So the Pro Tools would be great if we were interested in building servlets, but we're building portlets here.  Can we leverage any of these tools in Liferay?

The answer, my friend, is "Yes we can!".  Well, sort of.

So I've built portlets using Charts and Spreadsheets, but I haven't done anything with TestBench or TouchKit.

Honestly I'm not sure how much sense TestBench and TouchKit make in a portal setup since Vaadin only owns a portion of the page.  Maybe they work, maybe they don't, I wouldn't know until I tried.

There are two important caveats for using the Pro Tools in Liferay:

  1. A license file is necessary for the server (or each node in a cluster) to compile the widgetset with the Pro Tool widget.  For Liferay, you don't have to get a license per developer as listed on the Pro Tools license site because the developers are not compiling the widgetset, only the server (or nodes in the cluster) are.
  2. When compiling the widgetset, the Vaadin compiler will perform an internet call to verify the license.  This verification is outside of Liferay's control and therefore will not use Liferay's proxy settings for internet web access.  The server must have internet web access to the servers.  Make sure your network admin allows this kind of access from the server before undertaking this path.

Charts and Spreadsheets do work, however, so we'll start there.

Getting Vaadin Charts

The Vaadin Charts Overview provides an overview for the kinds of things you can do with Vaadin Charts, and the online demo shows what types of charts are available.

You can download the Vaadin Charts jar from the Add-On Directory (choose the Install/Download link on the right side, then click the download tab for the link to the zip file that contains the charts jar).  Expand the zip file so you'll have access to the jar file.

While you're on the directory page, be sure to click the Activate button to download your unique 30 day license code.

Vaadin 7 Control Panel Update

The first thing you're going to want to do is install/upgrade the Vaadin 7 Control Panel version  At the time this blog is published, the version is sitting in Liferay QA status for a week, but it should be out soon.  The new version has support for the Pro Tools as well as support for Vaadin 7.4.  Note that if this is the first time you've deployed the control panel you must restart your app server.

Compiling the WidgetSet

The Pro Tool widgets are basically Vaadin Add-Ons, but they have extra requirements for licenses which must be present at widgetset compile time.

This means that the license is only necessary when you compile the widgetset, but it is not necessary for runtime use of the Add-On.  So you need a license (well, one per server node) so the widgetset can be built as new widgets are added or a new Vaadin version is used, but otherwise the runtime use of the widget is unlimited (save whatever resource limitations you might have).

Before compiling the widgetset, we must deploy the Charts Add-On.

Go to the Vaadin 7 Control Panel and choose Add-Ons from the right side.  Click the "Choose File" button and locate the vaadin-charts-2.0.0.jar file from the downloaded zip earlier.  Click the "Upload Add-On" button to get to the confirmation page:

Deploy Charts Add On

Click "Yes" to deploy the Charts Add-On.  You'll then get to the deployed Add-Ons:

Vaadin Charts Selected

Normally you'd now be able to go and compile the widgetset with your new widgets and all would be fine.  But the Pro Tools require a license, so we'll add that by clicking Settings on the right side.

Enter Charts License

Remember the temporary license file you downloaded earlier?  Open the file using your favorite text editor and paste it into the input field labeled Vaadin Charts License.

Now you can click the "Compile WidgetSet" button and all will be fine.  If you get a license error during the compile, likely the charts license was not entered correctly or your server does not have internet access.

Building a Chart Portlet

So the shared environment is ready to go, so let's now create a simple chart portlet to see it all in action...

In order to take IDE preference out of the mix, I'm going to do everything w/ Maven directly.  Using an IDE works too, but your preferred IDE may be different from mine so if I show you the command line version, you should be able to make it work in your environment.

First we'll start a Maven project using the liferay-portlet-archetype:

mvn archetype:generate -DarchetypeGroupId=com.liferay.maven.archetypes -DarchetypeArtifactId=liferay-portlet-archetype -DarchetypeVersion=6.2.2 -DgroupId=com.dnebinger.vaadin -DartifactId=vaadin-charts-demo -Dversion=

This will give us a basic Liferay portlet project for Liferay MVC, but we'll be dumping Liferay MVC for the Vaadin shared environment.  We'll start by adding the following to the pom.xml file:

<!-- Add a repository definition so we can reference the Vaadin Add Ons -->
<!-- I tend to use commons lang to keep the code simpler -->

The portlet.xml file in the newly created project needs to be tweaked for our new Vaadin portlet.  Change the portlet.xml content to be:

<?xml version="1.0"?>

<portlet-app xmlns="" xmlns:xsi="" xsi:schemaLocation="" version="2.0">
		<!-- Normal Vaadin portlets will use this class as the portlet class -->

		<!-- Specify the main UI class which will be instantiated by the portlet -->
		<!-- Specify the use of the shared portal widgetset -->


The liferay-portlet.xml file needs some minor changes for Vaadin compatibility:

		<!-- Instanceable indicates whether multiple copies are allowed on the same page. -->
		<!-- ajaxable should always be false for Vaadin portlets -->

Because we're using the shared environment and provided scope in the pom.xml file, we need to add dependencies into the file:

author=Liferay, Inc.

# First the vaadin jars, then the addon jar(s), then spring jars.

Next is to develop the ChartsDemoUI class.  Below is one that I put together from the Vaadin charts demo site source for a pie chart:

package com.dnebinger.vaadin.charts.demo;

import java.util.Arrays;
import java.util.Random;

import com.vaadin.addon.charts.Chart;
import com.vaadin.addon.charts.model.ChartType;
import com.vaadin.addon.charts.model.Configuration;
import com.vaadin.addon.charts.model.DataSeries;
import com.vaadin.addon.charts.model.DataSeriesItem;
import com.vaadin.addon.charts.model.Labels;
import com.vaadin.addon.charts.model.PlotOptionsPie;
import com.vaadin.addon.charts.model.YAxis;
import com.vaadin.addon.charts.themes.ValoLightTheme;
import com.vaadin.annotations.Theme;
import com.vaadin.server.VaadinRequest;
import com.vaadin.ui.Component;
import com.vaadin.ui.UI;
import com.vaadin.ui.VerticalLayout;

public class ChartsDemoUI extends UI {

	private VerticalLayout mainLayout;

	protected void init(VaadinRequest request) {
		// create the main vertical layout
		mainLayout = new VerticalLayout();

		// give it some dimensions

		// set the layout as the content area.

    private static Random rand = new Random(0);
    private static Color[] colors = new ValoLightTheme().getColors();

    protected Component getChart() {
        Component ret = createChart();
        return ret;

    public static Chart createChart() {
        rand = new Random(0);

        Chart chart = new Chart(ChartType.PIE);

        Configuration conf = chart.getConfiguration();

        conf.setTitle("Browser market share, April, 2011");

        YAxis yaxis = new YAxis();
        yaxis.setTitle("Total percent market share");

        PlotOptionsPie pie = new PlotOptionsPie();


        DataSeries innerSeries = new DataSeries();
        PlotOptionsPie innerPieOptions = new PlotOptionsPie();
        innerPieOptions.setDataLabels(new Labels());
                "this.y > 5 ? : null");
        innerPieOptions.getDataLabels().setColor(new SolidColor(255, 255, 255));

        Color[] innerColors = Arrays.copyOf(colors, 5);
        innerSeries.setData(new String[] { "MSIE", "Firefox", "Chrome",
                "Safari", "Opera" }, new Number[] { 55.11, 21.63, 11.94, 7.15,
                2.14 }, innerColors);

        DataSeries outerSeries = new DataSeries();
        PlotOptionsPie outerSeriesOptions = new PlotOptionsPie();
        outerSeriesOptions.setDataLabels(new Labels());
                        "this.y > 1 ? ''+ +': '+ this.y +'%' : null");

        DataSeriesItem[] outerItems = new DataSeriesItem[] {
                /* @formatter:off */
                new DataSeriesItem("MSIE 6.0", 10.85, color(0)),
                new DataSeriesItem("MSIE 7.0", 7.35, color(0)),
                new DataSeriesItem("MSIE 8.0", 33.06, color(0)),
                new DataSeriesItem("MSIE 9.0", 2.81, color(0)),
                new DataSeriesItem("Firefox 2.0", 0.20, color(1)),
                new DataSeriesItem("Firefox 3.0", 0.83, color(1)),
                new DataSeriesItem("Firefox 3.5", 1.58, color(1)),
                new DataSeriesItem("Firefox 3.6", 13.12, color(1)),
                new DataSeriesItem("Firefox 4.0", 5.43, color(1)),
                new DataSeriesItem("Chrome 5.0", 0.12, color(2)),
                new DataSeriesItem("Chrome 6.0", 0.19, color(2)),
                new DataSeriesItem("Chrome 7.0", 0.12, color(2)),
                new DataSeriesItem("Chrome 8.0", 0.36, color(2)),
                new DataSeriesItem("Chrome 9.0", 0.32, color(2)),
                new DataSeriesItem("Chrome 10.0", 9.91, color(2)),
                new DataSeriesItem("Chrome 11.0", 0.50, color(2)),
                new DataSeriesItem("Chrome 12.0", 0.22, color(2)),
                new DataSeriesItem("Safari 5.0", 4.55, color(3)),
                new DataSeriesItem("Safari 4.0", 1.42, color(3)),
                new DataSeriesItem("Safari Win 5.0", 0.23, color(3)),
                new DataSeriesItem("Safari 4.1", 0.21, color(3)),
                new DataSeriesItem("Safari/Maxthon", 0.20, color(3)),
                new DataSeriesItem("Safari 3.1", 0.19, color(3)),
                new DataSeriesItem("Safari 4.1", 0.14, color(3)),
                new DataSeriesItem("Opera 9.x", 0.12, color(4)),
                new DataSeriesItem("Opera 10.x", 0.37, color(4)),
                new DataSeriesItem("Opera 11.x", 1.65, color(4))
                /* @formatter:on */

        conf.setSeries(innerSeries, outerSeries);

        return chart;

     * Add a small random factor to a color form the vaadin theme.
     * @param colorIndex
     *            the index of the color in the colors array.
     * @return the new color
    private static SolidColor color(int colorIndex) {
        SolidColor c = (SolidColor) colors[colorIndex];
        String cStr = c.toString().substring(1);

        int r = Integer.parseInt(cStr.substring(0, 2), 16);
        int g = Integer.parseInt(cStr.substring(2, 4), 16);
        int b = Integer.parseInt(cStr.substring(4, 6), 16);

        double opacity = (50 + rand.nextInt(95 - 50)) / 100.0;

        return new SolidColor(r, g, b, opacity);

Now we can build and deploy our shiny new Vaadin Charts portlet.  Drop it on a page and you'll get the following:

Sample Chart

The other charts from the Vaadin demo site,, can also be used.


Certainly the code for the chart may seem convoluted, but it is not all that bad.  Had I written the code instead of just copying the example code from, I would have added more comments to explain what was going on.  Let me just say that although the code seems convoluted, it is easy to create much simpler charts.

It's important to note that, just like all other Vaadin code, the chart is written and implemented completely in Java.  You don't have to worry about HTML, Javascript, etc.  You get a responsive chart that looks great and is backed by whatever data you gather to drive it (be it jdbc queries, data coming from ServiceBuilder or the Liferay APIs, etc).

As indicated earlier, I have created Vaadin portlets that use the Charts widget as well as the Spreadsheet widget.  Maybe I'll put together another blog post with a spreadsheet portlet, but for now take my word for it that it works.

A final word about Licensing...  The way that the Vaadin Pro Tools licenses work, by default you purchase a license per developer.  The developer, with the license, can build a Vaadin project where the widgetset is compiled for the project (either a Vaadin servlet or a Vaadin portlet from the Vaadin archetypes).  The compiled project can be built and deployed to an application server or cluster with no additional licensing issues.

Since the shared Vaadin environment compiles the widgetset on each node, a license is needed per instance when compiling the widgetset with one (or more) of the Pro Tools.  Note, however, that since the developers are not compiling the widgetset for the deployed project, developers themselves do not need the license, only the servers do.

Since the license applies to the compiled widgetset, not a compiled project, you can use unlimited instances of the widgets in your portlets.  1,000 charts?  Sure, no extra cost to build and display them.


Auto Vaadin Theme Deployment

General Blogs February 10, 2015 By David H Nebinger


So in two previous blogs I introduced Auto Vaadin Add On Deployment and Vaadin 7 Theming.  At the end of the Vaadin 7 Theming blog I said that there was a similar mechanism for handling the deployment of your themes using the Vaadin 7 Control Panel, the mechanism introduced in the Auto Vaadin Add On Deployment blog.

So this blog is going to cover that mechanism by showing how to handle Auto Vaadin Theme Deployment.


Follow the instructions from the Auto Vaadin Add On Deployment blog through the addition of the required-deployment-contexts entry in the file, then come back here...


We also need to add a startup action class that extends one of the classes from the Vaadin 7 Control Panel.  The class is below:

package com.dnebinger.liferay.vaadin.sample;

import com.dnebinger.liferay.vaadin.startup.AbstractVaadinThemeDeployStartupAction;
import org.apache.commons.lang.StringUtils;

import java.util.ArrayList;
import java.util.List;

 * SampleThemeDeployStartupAction: A sample class to demonstrate how to do automatic theme deployment.
 * @author dnebinger 
public class SampleThemeDeployStartupAction extends AbstractVaadinThemeDeployStartupAction {
   private static final String SAMPLE_THEME = "";
    * getThemeNames: Returns the names of the theme zip files from the WEB-INF/vaadin/themes directory that should be deployed.
    * @return List The list of theme names.
   protected List<String> getThemeNames() {
      List<String> names = new ArrayList<String>(1);


      return names;

    * getThemeVersion: Returns the version number to associate with the theme.
    * @param themeName Name of the theme file to get the version number for.
    * @return int The version number for the theme file.
   protected int getThemeVersion(String themeName) {
      if (StringUtils.isBlank(themeName))
      return 0;

      if (SAMPLE_THEME.equals(themeName)) {
         return 100;

      return 0;

This class does two things:

  1. It returns the list of themes to be deployed.
  2. It provides the version number to use for the theme.

To get the theme zip file, create and test your theme using the Vaadin 7 Control Panel.  When you are satisfied with the theme, use the Export button to export the theme as a zip file on your desktop.

The zip file must be added to your project in the src/main/webapp/WEB-INF/vaadin/themes folder.

The theme version number is used to determine if the theme has already been deployed.  If you are shipping an updated version of the theme, be sure to increment the version number.

We also need to add the src/webapp/WEB-INF/liferay-hook.xml file to add the hook to the portlet:

<?xml version="1.0"?>
<!DOCTYPE hook PUBLIC "-//Liferay//DTD Hook 6.2.0//EN" "">


We also need to create the src/resources/ file:

# - Properties for the hook to add the app startup action.

That's it!


With these changes in place, when you build and deploy the portlet, when it is started in the application container the startup action will process the theme file.

If it has either not been deployed before or if the version is greater than the currently installed version (considered a theme upgrade), the theme will be copied to the portal's html/VAADIN/themes directory and compiled to be ready for immediate use.

If it has already been deployed or the version is less than or equal to the deployed version, nothing happens (since it's already included).

So this eliminates the prework involved with deploying and compiling the themes, so you're back to just deploying your snazzy new Vaadin 7 portlet.

Just as with the automatic Add On deployment, you can include your theme with your project instead of treating them as separate deployments.

Updating Vaadin 7 Shared Environment

General Blogs February 8, 2015 By David H Nebinger


Vaadin 7 is an active project still in development.  New releases come out regularly with bug fixes (mostly browser compatibility).  New versions come out with new functionality, etc.

When using the Vaadin 7 shared environment, the version of Vaadin must be the same across the portal.

The reason is the compiled WidgetSets.  When you compile the WidgetSet, the compiled JavaScript is for the version of Vaadin that is being compiled against.  If you compile the WidgetSet using Vaadin 7.2.7, the code will not work so well against 7.2.6 or 7.3.

Keeping the version of Vaadin in sync in your portal has been difficult, but you have a tool to help you complete this task, the Vaadin 7 Control Panel.

Upgrading Vaadin

So upgrading the Vaadin 7 shared environment takes a couple of steps:

  1. Download the new version of Vaadin.
  2. Replace the existing Vaadin theme/widgetset currently in the portal with the new files from the new distribution.
  3. Recompile the custom themes and the widgetset using the deployed Add Ons.
  4. Replace the Vaadin jars for all Vaadin portlets with the version from the distribution.
  5. Restart the portal so the new jars take effect.

Except for the last step, The Vaadin 7 Control Panel will take care of all of these things automatically, you just have to enable a setting and then follow the upgrade procedure.

Enabling the Portlet Auto Update Feature

The portlet Auto Update feature is enabled/disabled in the Settings page of the Vaadin 7 Control Panel:


Check the "Update Portlets during version change." to enable the Auto Update feature.

NOTE: I recommend checking the "Automatically Compile WidgetSet on version change." checkbox.  Otherwise you must update and then manually compile the widgetset.  Since both must be done, why not save yourself some clicks and do it all at once?

Choosing The Version

The Overview page shows the currently installed Vaadin 7 version as well as the current stable version.  Note that to get this information, your server makes an HTTP request to; if your firewall does not allow this outbound traffic, you will not see a value for the stable version.

Click the Change Version link to change the version.

Again to populate this list, your server will open an HTTP connection to  If your firewall will not allow this connection, you will not get a list to display from.

That's okay, though, just follow the directions in the note to download the Vaadin 7 archive from manually and upload it using the form at the bottom.

Select the version from the list that you want to install:

After selecting your version, click the Change Version button to go to the next page.

NOTE: There are alpha, beta, pre-release and nightly builds of Vaadin available for download, but the Vaadin 7 Control Panel does not show these for installation.  You can use the manual approach to install one of these versions if you'd like.  Personally I don't believe that you should be trying to use non-stable versions of Vaadin in your portal (you will have enough to worry about using the stable versions).

You have one more chance to reconsider the upgrade.  Click Cancel to return to the Overview page or Change Version to start the upgrade process.

The upgrade process will update the status message at the top and the progress bar so you know what is going on during the upgrade.  A detailed log window appears below to provide all information relative to the upgrade steps.

When the upgrade process is done, you can click Done to return to the Overview page, but if you haven't enabled automatic WidgetSet compilation, click on the Compile Widgetset button and complete the widgetset compile.


When you are done with the upgrade process, the Overview page will reflect the upgraded version of Vaadin:

Note that after upgrading Vaadin 7, you should restart the application server.  This ensures that the correct version of Vaadin is being used by all Vaadin portlets.

As you can see, upgrading Vaadin 7 using the Vaadin 7 Control Panel just couldn't be easier.  And this is something you're going to want to do to keep up with all of the fixes for supported browsers.


Vaadin 7 HighCharts Portlet

General Blogs February 8, 2015 By David H Nebinger


So the last few Vaadin posts were on some basic introductory stuff, but not a whole lot of fun.  I thought I'd do a blog post on a quick and fun little Vaadin 7 portlet, one that uses HighCharts.

So I'm creating a portlet to show a pie chart of registered user ages (based on birthdate).  The fun part about this portlet is that it will use the Liferay API to access the user birthdates, but will use a DynamicQuery to check the birthdates, and we'll break it up into seven groups and display as a pie chart using HighCharts.  And the whole thing will be written for the Vaadin framework.

Project Setup

So first thing you need is the HighCharts for Vaadin 7 Add On.  You can use the Vaadin 7 Control Panel to deploy the Add On to your environment.  This Add On includes the Vaadin 7 widget for integrating with HighCharts in your Vaadin application, but you also need the HighCharts JavaScript file.

Initially I tried to use the version that comes with the Add On but quickly found that it was not going to work.  The JavaScript shipped with the Add On uses jQuery, but not jQuery in no conflict mode.  So that version of the HighCharts JavaScript won't work in the portal.

Fortunately, however, there is a viable alternative.  From the HighCharts Download page, one of the adapter options includes "Standalone framework" mode.  This adapter option does not rely on jQuery or any other JavaScript framework.

HighCharts Download

Select the Standalone Framework option and any other portions to include in the download you want.  The portlet being built in this blog uses the Pie Chart, so be sure to include that chart type.  I would selecting everything, that way you'll have a complete HighCharts JavaScript file to use in future charting portlets.

If you do not want the minified JavaScript, uncheck the "Compile code" checkbox before downloading.

Download the JavaScript file and save it for later.

Creating the Project

Since I'm using Intellij, I started a Maven project using the "liferay-portlet-archetype", similarly to the project I did for the "vaadin-sample-portlet" project.  I called the portlet and the project "vaadin-user-age-chart-portlet".

To create the portlet, there will be four classes:

  • UsersChartUI - This is the UI class for the portlet, it extends com.vaadin.ui.UI class.
  • DateRange - This is a utility class that calculates and keeps track of a date range.
  • UserAgeData - This is a utility class which retrieves the age data from the Liferay API.
  • UserPieChart - This is the extension class responsible for rendering the pie chart.


Let's start with the DateRange class.  It basically has the following:

package com.dnebinger.liferay.vaadin.userchart;

import java.util.Calendar;
import java.util.Date;

 * DateRange: A container for a date range.
 * Created by dnebinger on 2/6/15.
public class DateRange implements Serializable{
   private static final long serialVersionUID = 58547944852615871L;
   private Calendar startDate;
   private Calendar endDate;

    * DateRange: Constructor for the instance.
    * @param type
   public DateRange(final int type) {

      endDate = Calendar.getInstance();
      startDate = Calendar.getInstance();

      switch (type) {
         case UserAgeData.AGE_0_10:
            // end date is now

            // start date is just shy of 11 years ago.
            startDate.add(Calendar.YEAR, -11);
         case UserAgeData.AGE_11_20:
            endDate.add(Calendar.YEAR, -11);

            startDate.add(Calendar.YEAR, -21);
         case UserAgeData.AGE_21_30:
            endDate.add(Calendar.YEAR, -21);

            startDate.add(Calendar.YEAR, -31);
         case UserAgeData.AGE_31_40:
            endDate.add(Calendar.YEAR, -31);

            startDate.add(Calendar.YEAR, -41);
         case UserAgeData.AGE_41_50:
            endDate.add(Calendar.YEAR, -41);

            startDate.add(Calendar.YEAR, -51);
         case UserAgeData.AGE_51_60:
            endDate.add(Calendar.YEAR, -51);

            startDate.add(Calendar.YEAR, -61);
         case UserAgeData.AGE_60_PLUS:
            endDate.add(Calendar.YEAR, -61);

            startDate.add(Calendar.YEAR, -121);

      startDate.add(Calendar.DATE, 1);

    * getEndDate: Returns the end date in the range.
    * @return Date The end date.
   public Date getEndDate() {
      // start by verifying the day of year comparisons
      Calendar cal = Calendar.getInstance();

      if (cal.get(Calendar.DAY_OF_YEAR) != endDate.get(Calendar.DAY_OF_YEAR)) {
         // update start and end days
         endDate.add(Calendar.DATE, 1);
         startDate.add(Calendar.DATE, 1);

      return endDate.getTime();

    * getStartDate: Returns the start date in the range.
    * @return Date The start date.
   public Date getStartDate() {

      return startDate.getTime();

So the class is initialized for a type code and, given the type code, it sets up the start and end dates to cover the appropriate range.  Each time the starting and end dates are retrieved, the dates will be checked for possible increment (to keep the ranges intact).


The UserAgeData class uses the DynamicQuery API to count users that fall between the start and end date ranges.

package com.dnebinger.liferay.vaadin.userchart;

import com.liferay.portal.kernel.dao.orm.DynamicQuery;
import com.liferay.portal.kernel.dao.orm.DynamicQueryFactoryUtil;
import com.liferay.portal.kernel.dao.orm.RestrictionsFactoryUtil;
import com.liferay.portal.kernel.exception.SystemException;
import com.liferay.portal.kernel.log.Log;
import com.liferay.portal.kernel.log.LogFactoryUtil;
import com.liferay.portal.kernel.util.PortalClassLoaderUtil;
import com.liferay.portal.model.Contact;
import com.liferay.portal.service.UserLocalServiceUtil;

 * class UserAgeData: A class that contains or determines the user age data percentages.
public class UserAgeData {
   private static final Log logger = LogFactoryUtil.getLog(UserAgeData.class);

   // okay, we need to know when the data was retrieved
   private long timestamp;

   // and we need a container for the data
   private double[] percentages;

   private static final long ONE_DAY_MILLIS = 1000 * 1 * 60 * 60 * 24;

   public static final int AGE_0_10 = 0;
   public static final int AGE_11_20 = 1;
   public static final int AGE_21_30 = 2;
   public static final int AGE_31_40 = 3;
   public static final int AGE_41_50 = 4;
   public static final int AGE_51_60 = 5;
   public static final int AGE_60_PLUS = 6;

   private DateRange[] ranges = new DateRange[7];

    * UserAgeData: Constructor.
   public UserAgeData() {

      percentages = new double[7];
      timestamp = 0;

      for (int idx = 0; idx < 7; idx++) {
         ranges[idx] = new DateRange(idx);

    * getPercentages: Returns either the cached percentages or pulls the count.
    * @return double[] An array of 7 doubles with the age ranges.
   public double[] getPercentages() {
      // if we already have cached users
      if (timestamp > 0) {
         // need to check the timestamp
         long current = System.currentTimeMillis();

         if (current <= (timestamp + ONE_DAY_MILLIS)) {
            // we have values and they are still valid for caching

            if (logger.isDebugEnabled()) logger.debug("Found user data in cache, returning it.");

            return percentages;

      // if we get here then either we have no info or the info is stale.

      long[] counts = new long[7];
      long totalUsers = 0;

      // get the count of users
      for (int idx = 0; idx < 7; idx++) {
         counts[idx] = countUsers(ranges[idx]);
         if (logger.isDebugEnabled()) logger.debug("  " + idx + " has count " + counts[idx]);
         totalUsers += counts[idx];

      // now we can do the math...
      double total = Double.valueOf(totalUsers);

      for (int idx = 0; idx < 7; idx ++) {
         percentages[idx] = 100.0 * (Double.valueOf(counts[idx]) / total);

         if (logger.isDebugEnabled()) logger.debug("Percentage " + idx + " is " + percentages[idx] + "%");

      timestamp = System.currentTimeMillis();

      return percentages;

    * countUsers: Counts the number of users for the given date range.
    * @param range The date range to use for the query.
    * @return long The number of users
   protected long countUsers(DateRange range) {
      if (logger.isDebugEnabled()) logger.debug("Looking for birthday from " + range.getStartDate() + " to " + range.getEndDate() + ".");

      // create a new dynamic query for the Contact class (it has the birth dates).
      DynamicQuery dq = DynamicQueryFactoryUtil.forClass(Contact.class, PortalClassLoaderUtil.getClassLoader());

      // restrict the count so the birthday falls between the start and end date.
      dq.add(RestrictionsFactoryUtil.between("birthday", range.getStartDate(), range.getEndDate()));

      long count = -1;

      try {
         // count the users that satisfy the query.
         count =  UserLocalServiceUtil.dynamicQueryCount(dq);
      } catch (SystemException e) {
         logger.error("Error getting user count: " + e.getMessage(), e);

      if (logger.isDebugEnabled()) logger.debug("Found " + count + " users.");

      return count;

This class will keep a cache of counts that will apply for one day.  After 24 hours the cached values are discarded and the queries will be performed again.

Probably not the best implementation, but I'm not shooting for realtime accuracy, just mostly accurate data suitable for a chart on say a dashboard page.


Next comes the UserChartsUI class that implements the UI for the portlet.

package com.dnebinger.liferay.vaadin.userchart;

import com.vaadin.annotations.Theme;
import com.vaadin.server.VaadinRequest;
import com.vaadin.ui.Alignment;
import com.vaadin.ui.UI;
import com.vaadin.ui.VerticalLayout;
import com.dnebinger.vaadin.highcharts.UserPieChart;

 * Created by dnebinger on 2/6/15.
public class UsersChartUI extends UI {
   private VerticalLayout mainLayout;

   private UserPieChart pieChart;

   private static final UserAgeData userAgeData = new UserAgeData();

   protected void init(VaadinRequest vaadinRequest) {
      // create the main vertical layout
      mainLayout = new VerticalLayout();

      // give it a margin and space the internal components.

      // set the layout as the content area.



      pieChart = new UserPieChart();

      mainLayout.setComponentAlignment(pieChart, Alignment.TOP_CENTER);

      double[] percentages = userAgeData.getPercentages();

      pieChart.updateUsers(percentages[0], percentages[1],percentages[2],percentages[3],percentages[4],percentages[5],percentages[6]);

Nothing special in the UI, it creates a UserPieChart instance and places it in the layout.


The final class is the com.dnebinger.vaadin.highcharts.UserPieChart class.  This is the special integration class joining Vaadin 7 and HighCharts.

package com.dnebinger.vaadin.highcharts;

import com.dnebinger.liferay.vaadin.userchart.UserAgeData;
import com.liferay.portal.kernel.log.Log;
import com.liferay.portal.kernel.log.LogFactoryUtil;
import com.vaadin.annotations.JavaScript;

 * Created by dnebinger on 2/6/15.
@JavaScript({"highcharts-custom.js", "highcharts-connector-nojq.js"})
public class UserPieChart extends AbstractHighChart {
   private static final Log logger = LogFactoryUtil.getLog(UserAgeData.class);
   private static final long serialVersionUID = 7380693815312826144L;

    * updateUsers: Updates the pie chart using the given percentages.
    * @param age_0_10
    * @param age_11_20
    * @param age_21_30
    * @param age_31_40
    * @param age_41_50
    * @param age_51_60
    * @param age_60_plus
   public void updateUsers(final double age_0_10, final double age_11_20, final double age_21_30, final double age_31_40, final double age_41_50, final double age_51_60, final double age_60_plus) {

      StringBuilder sb = new StringBuilder("var options = { ");

      sb.append("chart: {");
      sb.append("plotBackgroundColor: null,");
      sb.append("plotBorderWidth: null,");
      sb.append("plotShadow: false");
      sb.append("title: {");
      sb.append("text: 'Age Breakdown for Registered Users'");
      sb.append("plotOptions: {");
      sb.append("pie: {");
      sb.append("allowPointSelect: true,");
      sb.append("cursor: 'pointer',");
      sb.append("dataLabels: {");
      sb.append("enabled: false");
      sb.append("showInLegend: true");
      sb.append("series: [{");
      sb.append("type: 'pie',");
      sb.append("name: 'Age Breakdown',");
      sb.append("data: [");
      sb.append("['Zero to 10', ").append(format(age_0_10)).append("],");
      sb.append("['11 to 20', ").append(format(age_11_20)).append("],");
      sb.append("['21 to 30', ").append(format(age_21_30)).append("],");
      sb.append("['31 to 40', ").append(format(age_31_40)).append("],");
      sb.append("['41 to 50', ").append(format(age_41_50)).append("],");
      sb.append("['51 to 60', ").append(format(age_51_60)).append("],");
      sb.append("['Over 60', ").append(format(age_60_plus)).append(']');


      // close the options
      sb.append(" };");

      String chart = sb.toString();

      if (logger.isDebugEnabled()) logger.debug(chart);


   protected String format(final double val) {
      String s = String.format("%s", val);

      int pos = s.indexOf('.');

      if (pos < 0) return s + ".0";

      double x = Double.valueOf(Double.valueOf((val * 10.0) + 0.5).longValue()) / 10.0;

      return s.substring(0, pos+2);

This class requires the most explanation, so here we go.

The first thing is the @JavaScript annotation.  This is a Vaadin 7 annotation that is used to inject JavaScript files into the response stream for the portlet.  For this portlet we need the highcharts-custom.js file (this will be the one that you downloaded earlier) as well as a highcharts-connector-nojq.js file which we will add later.

The updateUsers() method takes the 7 percentage values and outputs JavaScript to create and populate an options object, this object will be used by the HighCharts library to render the chart.  I used a simple StringBuilder to build the JavaScript, but a better way would have been to use the org.json.JSONObject class to construct an object and output it as a string (that way you don't have to worry about syntax, quoting, etc.).

The last method, the format() method, is a simple method to output a double as a string to a single decimal place.  Nothing fancy, but it will work.

Adding the JavaScript Files

As previously stated, we need to add two javascript files to the project, but these do not go in the normal places.  Since we used the @JavaScript annotation in the UserPieChart class, we have to put them into the project's src/main/resources folder as the JavaScript files need to be in the class path.

Since our Java class is com.dnebinger.vaadin.highcharts.UserPieChart that has the @JavaScript annotation, our JavaScript files have to be in src/main/resources/com/dnebinger/vaadin/highcharts.  The HighCharts JavaScript file that we downloaded earlier must be copied to this directory named "highcharts-custom.js" (to match the value we used in the @JavaScript annotation).

The second javascript file we will create in this directory is "highcharts-connector-nojq.js".  The contents of this file should be:

window.com_dnebinger_vaadin_highcharts_UserPieChart = function () {

   this.onStateChange = function () {
      // read state
      var domId = this.getState().domId;
      var hcjs = this.getState().hcjs;

      // evaluate highcharts JS which needs to define var "options"

        // update the renderTo to point at the dom element for the chart.
        if (options.chart === undefined) {
            options.chart = {renderTo: domId};
        } else {
            options.chart.renderTo = domId;
        // create the new highcharts object to render the chart.
        var chart1 = new Highcharts.Chart(options);

This is a connector JavaScript function to bridge Vaadin 7 and HighCharts.  Note the name of the function matches the package path and class for the function name, except the periods are replaced with underscores.

Since the current HighCharts Add On relies on jQuery, the connector function that comes with the Add On will just not work in our new implementation for the portal.  This function does not rely on jQuery and will ensure the correct stuff happens.


So far I've presented some code, but it's not all that much.  Some utility classes for date calculations, a wrapper class encapsulating the DynamicQuery access, our necessary UI class for the portlet and a UserPieChart class to encapsulate the HighCharts access.

The results of this code can be seen below:

User Ages Pie Chart

Had I taken a little time to create some users with suitable dates, I could make the chart take on any sort of view.  Since I'm using a stock Liferay bundle with my own extra user account, I have 3 users that must be broken down and displayed.

I think you must agree, however, that all in all this is an extremely simple portlet.  It should be easy to see how you could leverage a number of small Vaadin 7 portlets to create a dashboard page with quite a few graphs on it.

If I were asked to do something like that, I'd make a few changes:

If there were more than say 4 or 5 graphs on the page, I'd put the highcharts-custom.js JavaScript file into the theme.  I'd then remove it from the @JavaScript annotation.  The connector JavaScript would remain, but it is so small and is bound to the chart package/class anyway.

If there are more than two on the page but less than 5, I would at least put the highcharts-custom.js into the portlet javascript resources and pull in using the <header-portlet-javascript /> tag in liferay-portlet.xml.  That would at least allow the portal to import a single copy of the JavaScript rather than multiple copies.  Again it would be removed from the @JavaScript annotation, but the connector JavaScript would remain.

Note: Before anyone asks, I'm not going to be putting the code for this portlet online.  Without the HighCharts JavaScript, it's not really complete and I can't distribute the HighCharts JavaScript myself.  However, all of the code for the portlet is here in the blog and I've left nothing out.  If you have any problems reconstituting the portlet, feel free to ask.


Vaadin 7 Theming

General Blogs February 5, 2015 By David H Nebinger


Wow, been staying up late cranking out some Vaadin blogs.  It's starting to catch up with me, but I have one more to add to the pile - Theming.

Vaadin Themes in Liferay

Vaadin in the portal is challenging because of theming.  In a Liferay portal window, well the surrounding frame is all managed and styled by the Liferay theme.  This poses a special problem for Vaadin because Vaadin portlets, like Vaadin servlets, want to be styled exclusively by a separate Vaadin theme.

In a Vaadin servlet this isn't a problem because there is no surrounding styling to worry about, but in the portal the Vaadin theme is styling a portlet within the context of the portal's theme, and these two are typically not aware of the impact they can have on each other.

I'll wager that any Vaadin theme you try, from the standard Vaadin themes to those available from, every one of these will end up rendering differently within the portal than from a servlet.

Some of the rendering differences will be minor, some will not.

Usually it comes down to this - Vaadin themes always assume they are starting from a blank slate, a totally unstyled starting point that the Vaadin styling can build off of.

In Liferay, however, this is never the case.  When Vaadin gets to start styling tags there's a whole mountain of CSS styling already in place, styling that the Vaadin theme doesn't think it has to undo.  For example, a Vaadin theme can style a tag by giving a "margin-left: 20px" style because it will assume that the tag has no margin styling from Vaadin; the problems arise when the Liferay theme applies generic margins to an element that Vaadin isn't undoing.  The correct Vaadin styling that should apply is a left margin of 20px but a top, right, and bottom margin of 0px if it doesn't want or need them.

So as you move forward creating Vaadin themes, keep in mind that you are probably not just styling Vaadin elements, you are also undoing or mixing in the styling from your Liferay theme.

Keep in mind a few key points to use in Vaadin theming:

  • You can specifically undo a style.  For example, setting a margin to 0px when you don't want a margin rather than assuming there just isn't one.
  • You can use !important to force a rule, but as always the more you use it the harder it is to work around it.
  • Higher specificity always rules.  So if you can match on a path or on multiple classes, writing a rule that results in higher specificity will give your rules precedence over inherited styling from the Liferay theme.

When to Theme in Vaadin

You create themes in Vaadin for the same reasons you create themes in Liferay - to package a set of styling rules that can be reused and applied to multiple portlets.

But you will also finding yourself creating themes because it's the only effective way to style your Vaadin portlets.

Many aspects of your Liferay theme that you hope would apply to your Vaadin elements simply won't because the Vaadin theme is in play.  The liferay-portlet.xml file way of defining CSS to include in the portlet, well even that starts breaking down within the Vaadin portlet where the Vaadin theme is getting in the way.

By creating and maintaining a Vaadin theme for your Vaadin portlets, you get a theme which will style the Vaadin widgets just the way you need every time.

How to Theme Vaadin Portlets

So you theme your Vaadin portlets in two ways.  The first is to add style classes to your widgets in the Java code and the second is to write CSS (usually from SCSS) that define the style rules for the classes.

Every Vaadin widget, from the UI class all the way down to a caption on a label, every widget can be assigned style classes.  You decorate your Vaadin widgets with classes when you need to style them differently from the norm.

For example, we're going to be taking the vaadin-sample-portlet project and modifying the look and feel of the user detail page.  We have these requirements to:

  • Change the caption for required elements red.
  • Increase the font size for the displayed values.
  • Indent the displayed values from their captions.
  • Adjust some margins so the elements are not all cramped together.

As a reminder, here's how the user details panel looks before styling is applied:

Existing User Detail Panel

Not very pretty, I think we'd all agree on that.

Adding Style Names to Vaadin Widgets

Now based upon our requirements we know that we are going to be indenting all of the values from the captions and we're also going to change the "required" caption to red.  We'll assume that the Name is our only required field (hey, this is just an example, I know email and screen name are also required, but how fun is that to make them all the same?).

So we'll use two classes, "indented" and "required-cap".  We'll be using two methods on the widgets, the setStyleName() and addStyleName() method.  The set method does that, it sets a single value, the add method adds additional style classes beyond the first.

Below is the code we'll use to style the widgets:

// add some classes to the widgets, we'll sort them out in the theme


Just a quick word on style names.  Vaadin actually does some weird things with the class names that get applied, you will actually end up with one or two classes for each style name.  For example, the userId widget is a Label instance.  The HTML that results for this widget is:

Generated HTML

The userId element is the outer div for the "v-widget" and two inner divs.  The first inner div is the caption, the "User ID:" string.  The second inner div is the label, the "11005" value.

Note the classes on the second inner div, the "v-label" div.  It has both the "indented" and "v-label-indented" classes.  The first inner div, the "v-caption" div, that only has a manufactured class of "v-caption-indented".

So your simple assignment of "indented" as a style name results in classes that match the name but also classes prefixed with the widget type.

Although this may seem odd at first, it is actually kind of useful.  You can style using the generic "indented" class that would apply to all widgets or you can provide specific and different styling for indented captions vs indented labels.  The user portrait is an instance of an Embedded object; it's unique class is "v-embedded-indented".  When we create our theme we'll be taking advantage of these differences.

Creating a Vaadin Theme

So creating a Vaadin theme is pretty easy when using the Vaadin 7 Control Panel.

The Vaadin Theme panel lists the current themes available in your Vaadin shared environment:

Current Themes

In the window above, all of the listed themes are the standard themes.  These are handled differently than custom themes in that they cannot be edited, compiled or deleted.  Your custom themes can be edited, compiled or deleted.

Click the "Create Theme" button to create a theme.  We'll name our new theme "sample".  Note that theme names become part of the URL, so some characters will be invalid.

Creating a Theme

With our new theme created, it will be in the theme list.  We'll be selecting it so we can edit the theme.

When editing a theme, you begin from the Theme Structure panel with a tree view on the left showing all files included in the theme and a preview area on the right.  The preview area is read-only.

Viewing Theme Files

On the left is a tree view of the files that are in the theme.  All new themes will start with two files, the styles.scss file is the main one used to compile the theme and the second file is an SCSS file named from the theme.

You can actually right-click on the folder to create new subfolders, upload assets (such as images) or delete files.  There is no limit to what you can build into your theme.

The right side is a preview panel to view the current contents of the file (it will also preview image files).  The preview control is based on the Ace Editor Vaadin Add On and it is a syntax-aware code viewing/editing control.  

At the bottom of the panel is an Edit button, click the button to open the edit dialog.

By default, every custom theme inherits from the Liferay Vaadin theme.  Remember the Liferay Vaadin theme is not your Liferay theme, it's actually an adaptation of the Liferay Classic theme as a Vaadin theme.  You can change your theme inheritance to any other installed theme.  The Vaadin 7 Control Panel uses the Liferay theme as the default base theme because this has the least amount of conflict with the Liferay themes (well, the Liferay Classic theme, your Liferay theme can have it's own incompatibilities).

So, given our requirements we will add our own style definitions to handle our recently added classes:

Note how we've handled the v-label-indented and v-embedded-indented differently.  Also note the overlap in the margin-left and margin-top values.  We could have used a rule for the "indented" class that had the two margin settings and a rule for "v-label-indented" to have the margin-bottom and font-size changes.

Anyway, we would continue editing this file, adding other files, adding assets that we needed such as background images or sprites, whatever was needed to flush out the theme.  When finished, we click on the Back link from the top right of the Theme Structure panel to return to the theme list page.

On the theme list page, we have to choose the "Compile Theme" button to compile our theme (compiling the theme converts the SCSS into standard CSS for serving to the browser).

When we return to the theme list, we will see our theme with a corresponding compile date.

Like Vaadin Add Ons, when you are working in a cluster the theme needs to be copied to each node and compiled separately.  Fortunately the "Export Theme" and "Import Theme" buttons can help with this.

The Export Theme function bundles the theme file into a zip and uses the browser to download the theme to your desktop.  The Import Theme function lets you browse for a theme zip file on your desktop to upload to the server.

After importing the theme, you should compile the theme so it is ready on the node.  Repeat this step for all nodes in the cluster.

The Vaadin 7 Control Panel also supports automated theme deployment similar to the automated Add On deployment discussed in a previous blog entry.  A future blog entry will cover the automated theme deployment functionality of the Vaadin 7 Control Panel.

So our new sample theme is done and ready for use in our portlets, but our vaadin-sample-portlet project needs one more change to use the theme.

Assigning the Vaadin Theme for a Vaadin Portlet

We have one minor change we must make so the vaadin-sample-portlet uses the new sample theme.

In the com.dnebinger.liferay.vaadin.sample.UsersUI class we had an annotation indicating we wanted to use the liferay theme:

// Use the standard Liferay theme for the widgets.
public class UsersUI extends UI implements Page.BrowserWindowResizeListener {

We need to change the annotation for our sample theme:

// Use our own theme
public class UsersUI extends UI implements Page.BrowserWindowResizeListener {

Through this annotation our portlet will always use the sample theme.  If the sample theme is not available, Vaadin will fall back to a standard theme (the Liferay theme).

Beginning with Vaadin 7.3.0, you can call the UI's setTheme() method with a theme name, allowing for a runtime theme change.

Page Resizing

If you were closely following the previous blog posting, the addition of the "implements Page.BrowserWindowResizeListener" would stand out as a new addition.

Although this isn't necessary Vaadin Theme related, it does affect the view presentation, so I'm including it here as a bonus.

If you remember, there was code in the UsersUI init() method that set the height of the UI to 600px.  This is an issue for Vaadin that the UI has to have a defined height or it will not show.  However, 600px is a large and arbitrary value, surely there is a way we could size the portlet better.

And there is.  The com.vaadin.ui.Page class has access to the current browser details.  To demonstrate, I decided I would make my minimum portlet size 200px but, if there was more vertical space available, I'd expand to use it.  Not a very complex implementation, but it shows what is possible.  I ended up with the following:

int height = 200;

Page pg = Page.getCurrent();

if (pg != null)  {
   int browserHeight = pg.getBrowserWindowHeight();

   // so normally you may know that there is stuff on your page that should normally be about 800 px high.
   // we would want a minimum of 200 px in height, but if the browser height is 1500 why not grow to take
   // advantage of it?

   height = browserHeight - 800;

   if (height < 200) height = 200;

setHeight(height + "px");

This code in the init() method allows for choosing a dynamic starting size, but what if we want to change the height based upon the browser window size changing?  We can deal with that by registering as a browser resize listener.

First our class implements the Page.BrowserWindowResizeListener interface, then we can register as a listener in the UsersUI init() method:

if (pg != null) pg.addBrowserWindowResizeListener(this);

And our implementation of the interface uses similar logic to handle the resize:

 * browserWindowResized: Event handler for the browser window resize.
 * @param browserWindowResizeEvent
public void browserWindowResized(Page.BrowserWindowResizeEvent browserWindowResizeEvent) {
   int bheight = browserWindowResizeEvent.getHeight();

   int height = bheight - 800;

   if (height < 200) height = 200;

   setHeight(height + "px");

Like I said, this implementation is not the best.  If your height of stuff above the portlet is 800 px on a wide screen but grows to 1200 px when shrunk so the upper content wraps, well then the math is all wrong.  Also there's no thought given to the footer height in the calculation.

But the point was not to show a perfect implementation, just to show some capability.


So our theme is compiled and ready to go.  The code changes are complete so we build and deploy the updated portlet.  When we see our results, they look a lot better than the starting image:

Themed User Details

Compared to the starting image, it is easy to see that applying some Vaadin theming will make your Vaadin portlets just look better.  No, this is still probably not a view that will excite anyone, but after seeing how easy it is to edit and compile a theme using the Vaadin 7 Control Panel, it should be clear that it could be styled to get it up to anyone's expectations.

An important feature of the shared Vaadin environment and theme editing using the Vaadin 7 Control Panel: theme changes take effect (almost) immediately, no deployments necessary.  After you compile the theme, any time the Vaadin portlet is refreshed or a new user starts an instance, they'll get the updated theme.  This can be a big advantage if deployments within your organization are significant events that must be scheduled well in advance.

Happy Theming!

Auto Vaadin Add On Deployment

General Blogs February 4, 2015 By David H Nebinger


In my last blog post, I closed with the following:

If you have the Vaadin 7 Control Panel installed and you've deployed the LazyPagedContainer Add On, you can download and deploy the vaadin-sample-portlet-1.0-SNAPSHOT.war file directly from this blog.

This is not completely correct.  The Vaadin 7 Control Panel includes functionality to deploy Vaadin Add Ons at deployment time.

Originally I added this feature to support deployment of Vaadin 7 portlets from the Liferay MarketPlace.  I want to be able to distribute Vaadin 7 plugins without giving the user a whole list of dependencies that have to be satisfied to use the plugin.  With this feature, deploying the plugin into the environment would also deploy the Add On, recompile the widgetset and the portlet would be ready to go.  The only requirement would be the Vaadin 7 Control Panel.

This feature has another use case that is valuable for enterprises - artifact deployment to multiple environments.

Imagine you're a developer and you've just completed development of your next enterprise Vaadin 7 portlet.  It works great in your local development environment, but to implementent all of the requirements you needed to use some additional Add Ons that are not currently in your environment, namely the Lazy Paged Container.

In your enterprise, you have a bunch of environments - testing environments, QA environments, production environment in a cluster...  Normally before your portlet could get deployed to those environments, you'd have to ensure the Add On was deployed, the widgetset compiled, etc., and then your portlet could be deployed.  Some of these environments you might have access to deploy the Add On to, but others may involve a separate Operations group that will look at pushing out the Add On as a deployment of it's own.

Well, the same feature to auto deploy Add Ons for MarketPlace plugins will also help in this environment.  Using the auto Add On deployment feature, you would augment your portlet to push the Lazy Paged Container during your portlet deployment - whatever your enterprise deployment process, the deployment of your Vaadin 7 portlet will deploy your Add On too.

In the remainder of this blog post we'll adapt the vaadin-sample-portlet project to handle the auto deploy of the Lazy Paged Container Add On.


The Vaadin 7 Control Panel comes with a service jar that you will need in your project.  You should install the jar to your local Maven repository or deploy it to your local Nexus repository so it can be included in your project.  If you navigate to the vaadin7-control-panel-portlet/WEB-INF/lib directory on your app server, you'll find the vaadin7-control-panel-portlet-service-version.jar file (where version will be the version number for the service jar).

To install the jar to your local Maven repository, run the following command from this directory:

mvn install:install-file -Dfile=vaadin7-control-panel-portlet-service-version.jar \
  -Dgroupid=com.dnebinger.liferay -DartifactId=vaadin7-control-panel-portlet-service \
  -Dversion=version -Dpackaging=jar

Replace version with the version from the filename, note that there are two instances in the command line.

To deploy the jar to your local Nexus repo, your command line will be:

mvn deploy:deploy-file -Dfile=vaadin7-control-panel-portlet-service-version.jar \
  -Dgroupid=com.dnebinger.liferay -DartifactId=vaadin7-control-panel-portlet-service \
  -Dversion=version -Dpackaging=jar -Durl=http://user:pswd@nexus
Again the version number needs to be entered in the command line and the url should be changed to your local repository URL.

Project Changes

The first change will be in the pom.xml file.  We'll be adding a dependency on the service jar and removing the provided scope for the Lazy Paged Container artifact.

The new dependencies, based upon my local version, are:


Because we removed the provided scope from the pom.xml file, Maven will include the jar in the war's WEB-INF/lib directory.  Since the portal may not have the Add On jar (if it hasn't been deployed before), we will remove it as a portal dependency jar.  Also, since we're using the Vaadin 7 Control Panel service jar, we'll add it as a required deployment context so the portlet will not load unless the Vaadin 7 Control Panel is deployed and ready.  Below is the updated file:

author=Vaadin On Liferay

# First the vaadin jars, then spring jars.

# We are dependent upon the Vaadin 7 Control Panel since we use the service jar.

The next change is to add a startup action class extending one from the Vaadin 7 Control Panel service jar.  It's really a simple class, so it is below:

package com.dnebinger.liferay.vaadin.sample;

import com.dnebinger.liferay.vaadin.startup.AbstractVaadinAddonDeployStartupAction;

import java.util.ArrayList;
import java.util.List;

 * class LazyPagedContainerDeployStartupAction: A startup action class to deploy the Lazy Paged Container Vaadin Add On.
public class LazyPagedContainerDeployStartupAction extends AbstractVaadinAddonDeployStartupAction {
   private static final String LPC_JAR = "LazyPagedContainer.jar";

    * getAddonNames: Returns the names of all jars from the WEB-INF/vaadin/addons directory that should be deployed.
    * @return List The list of jar filenames.
   protected List<String> getAddonNames() {
      List<String> names = new ArrayList<String>(1);


      return names;

    * getAddonVersion: Returns the encoded version for the Add On jar with the given name.
    * Version is encoded without periods but complete enough so updates will be deployed correctly.
    * For this example, Lazy Paged Container is verison 1.0.0 so the value we will return is 100.  That way if a
    * 1.1.0 or 1.0.1 or 2.0.0 version comes out, we can follow the version coding to get 110, 101, and 200 and
    * trigger the update deployment.
    * @param addonName Name of the Add On to get the version for.
    * @return int The encoded version number.
   protected int getAddonVersion(String addonName) {
      // you should be returning a version number for every Add On that you're hoping to deploy.
      if (LPC_JAR.equals(addonName)) {
         return 100;
      return 0;

When the startup action is invoked, the named Add On must be found in the portlet's WEB-INF/vaadin/addons directory and match the given name.  So create a WEB-INF/vaadin/addons directory and copy the Add On jar(s) to this directory.

The final change is to add the pieces so Liferay will handle our startup action.  We will do this by adding a hook to the portlet to add the portal properties for the startup action.

First we need to add the src/webapp/WEB-INF/liferay-hook.xml file:

<?xml version="1.0"?>
<!DOCTYPE hook PUBLIC "-//Liferay//DTD Hook 6.2.0//EN" "">


We also need to create the src/resources/ file:

# - Properties for the hook to add the app startup action.

That's it!


With these changes in place, when you build and deploy the portlet, when it is started in the application container the startup action will process the LazyPagedContainer.jar file.

If it has either not been deployed before or if the version is greater than the currently installed version (considered an Add On upgrade), the jar will be copied to the portal's WEB-INF/lib directory, it will be added as a selected Add On (will show as checked in the Vaadin 7 Control Panel), and the widgetset will be rebuilt including the jar.

If it has already been deployed or the version is less than or equal to the deployed version, nothing happens (since it's already included).

So this eliminates the prework involved with getting all of the required Add Ons out of the way so you're back to just deploying your snazzy new Vaadin 7 portlet.

Developing a Portlet in Vaadin 7

General Blogs February 3, 2015 By David H Nebinger


So I wanted to provide an example Vaadin portlet built using the Vaadin 7 shared environment.  Currently I've been migrating my general development efforts over to Intellij, so I thought this would be a good time to try out creating a Vaadin 7 portlet in Intellij and Maven.  The results are outlined in the rest of this blog entry.

Creating the Project

So to create the project, I just used Intellij's Maven integration to create a Liferay portlet.  From the starting page, I chose "Create New Project".

Intellij Starting Page

For lack of anything better, I used the Maven type to create a new Liferay portlet.  I used the liferay-portlet-archetype which, by default, creates a new Liferay MVC portlet, but we'll take care to remove that later on.  It will provide all of the right plumbing though to get the project started.

Create Maven Project

For the new project you have to specify your Maven artifact details.  The values I used are below.  One important note, there are some versions of Liferay and/or some application servers which require a plugin to include the plugin type as a suffix in the name.  I tend to just do that now for all Liferay artifacts just so I automatically include "-portlet" in the artifact id.

Maven Archetype Details

Next page you can review and, if necessary, change the settings being passed to Maven:

Maven Settings

Finally specify the project name which I've kept the same as my Maven artifactId.

Project Name

Updating the Project Files

Before we start creating the Vaadin source files we have to modify some of the project files.

The first easy modification to the project is to delete the view.jsp file, the icon.png file, the js directory and the css directory, all generated for the portlet by the archetype.  These files/directories will not be needed so there's no reason to keep them any longer.

Update pom.xml

The basic pom.xml file created by the archetype is set up for a Liferay MVC portlet.  We need to add some parts to it to leverage the Vaadin shared environment.

Before the <dependencies /> section, we have to define a new <repository />.  Insert the following:


This adds the Vaadin Add On repository definition to the project so Maven will be able to find dependency jars.

We also need to add a number of dependencies to the project:


This pulls in all of the Vaadin jars and dependencies.  Additionally I've included commons-lang and the lazy-paged-container Add On jar that the portlet will be using.

Note that the <scope /> being used for all of the jars is "provided".  Maven will include the jars to satisfy compiling the Java code but will exclude them from the built war file artifact.

Updating the Portlet.xml File

The archetype generated an initial portlet.xml file that contains the values for the Liferay MVC portlet.  We'll strip that portlet definition out and replace it with the one we need for Vaadin:

       <!-- Keep portlet names simple -->

       <!-- Normal Vaadin portlets will use this class as the portlet class -->

       <!-- Specify the main UI class which will be instantiated by the portlet -->
       <!-- Specify the use of the shared portal widgetset -->

      <title>Vaadin Sample</title>
      <short-title>Vaadin Sample</short-title>
      <keywords>vaadin sample portlet liferay users lazy container</keywords>

The important parts here are the <portlet-class /> value and the UI init param.

The given portlet class is the class to use for Vaadin 7-based portlets.  Unlike GenericPortlet where you often need to subclass the portlet to provide an implementation with your business logic, the VaadinPortlet class rarely (if ever) needs to be subclassed.

The UI <init-param /> value is the class for the main UI class for your portlet.  This class extends com.vaadin.ui.UI and handles the initialization of the Vaadin portlet views.  The UsersUI class referenced here will be discussed later.

The remainder of the <portlet /> contents are standard entries used by many other portlets.  Customize as necessary.

Although not highlighted here in this blog, you should update the liferay-display.xml file using the value from the <portlet-name /> tag.

Updating the Liferay-Portlet.xml File

The next file to update is the liferay-portlet.xml file.  Again the Liferay MVC portlet entry will be stripped, and the Vaadin portlet entry must be added:

       <!-- Must match the value of the <portlet-name /> tag from portlet.xml. -->
       <!-- Instanceable indicates whether multiple copies are allowed on the same page. -->
       <!-- ajaxable should always be false for Vaadin portlets -->

Not really much here.  Javascript and CSS files are not normally used (you don't need separate JS files for Vaadin and styling comes from the Vaadin theme).  Many of the other standard values used in other portlet frameworks are not necessary for Vaadin portlets.

The only tag that is necessary is the <ajaxable /> tag, this value should be set to false for all Vaadin portlets.

Updating the Liferay-Plugin-Package.Properties File

The next file to modify is the file.  The change we're going to make here is the inclusion of the portal dependency jars that will be included during hot deployment.

Our file looks like:

author=Vaadin On Liferay

# First the vaadin jars, then the addon jar(s), then spring jars.

Remember all of those provided scopes in the pom.xml file?  By declaring them as provided, Maven would not include the jars in the /WEB-INF/lib directory.  But since we need them after deployment, we list them as portal-dependency-jars so they all get pulled in.

By listing the Vaadin jars, the version of Vaadin 7 the portal is using will get pulled into your portlet during hot deployment.  This will ensure that your portlet has the same Vaadin version as the portal, and when Vaadin is upgraded (using the Vaadin 7 Control Panel), the version of Vaadin used by this portlet will be upgraded also.

The LazyPagedContainer.jar file is also listed as a dependency.  In my last blog entry, I demonstrated how to deploy the LazyPagedContainer Add On using the Vaadin 7 Control Panel.  If I had any other Add Ons that I wanted to use in this portlet, I would first deploy them using the Vaadin 7 Control Panel and recompile the widgetset.  Then I can include the jar file(s) as portal-dependency-jar entries and I can use the Add On(s) in my portlet.

Writing the Vaadin Portlet Code

Now this is where I need to back peddle a little bit...

Remember when I said I was going to do this portlet in Intellij?  Well that really was my plan.  But I got to this point where I was ready to start my CustomComponent subclasses and I just stopped.  Basically I was just unwilling to hand-code the initial component classes, defining all of the layouts and widgets, figuring out their alignment, etc.

So I quickly caved and fired up my trusty version of Eclipse that has the Vaadin IDE plugin installed.  If you are going to be doing Vaadin development, either for servlets or portlets or both, you really, really need this Eclipse plugin.

I mean, sure, I could decide to use a primary layout as a VerticalLayout, the first entry being a HorizontalLayout that has a VerticalLayout on the left (with the user detail labels) and an Embedded for the user portrait on the right, and the main VerticalLayout has a Button that is right aligned for the Back link.  I could declare all of the private members, write all the code to construct and initialize the components and wire them into the appropriate heirarchy.

But who would when you can lay everything out graphically?

Vaadin IDE

Isn't that sexy?  You can't do anything like this with your JSP frameworks, your javascript frameworks, your jsf frameworks, ...  And this isn't some storyboard or anything like that, behind the scenes the Vaadin IDE is reworking the Java code that implements what you see in this view.  In the end, the generated code is by no means complete (no event handlers are wired, etc.), but this is such a great head start towards building your views it is just too hard for me to give up.

So basically I started my Eclipse environment and created a fake Vaadin servlet so I could start my CustomComponents that I would be using in my portlet.  I laid them out visually such as you see above.  When I was done with the visual layout, I switched over to the code view to find all of the Java code the Vaadin IDE generated for me, copied it all, then switched over to Intellij to create the java classes and pasted all of the Vaadin IDE-generated code into my new class in Intellij.

Unfortunately there is no current Vaadin IDE plugin being built for Intellij (that I know of), so at some point I'm going to be faced with the choice to continue this awkward process (since I don't want to give up the Vaadin IDE) or bail on Intellij and stick with Eclipse to keep the Vaadin IDE close.  I'm new to Intellij and haven't developed the commitment to it that others have, so I'm not sure which way I'll end up going, but I'll keep you up to date.

Now back to the code...

Portlet Component Decomposition

For my interface, I decomposed it into the following components:

  • A detail component - The basic interface shown above, simply a page which shows basic user details and the user portrait.  Works on a single user.
  • A list component - Shows the list of Liferay users.  Will leverage the LazyPagedContainer to manage the pull of data from the Liferay API.
  • A tab component - Tab components (with tabs hidden) happen to be an easy way to quickly switch back and forth between the (hidden) tabs.  On one tab I'll put the list component and the other tab will have the detail component.  When a user is selected from the list, I'll switch tabs and update the detail component.  That back button on the detail page?  That will just get the tab component to switch back to the list component.
  • The UI class - This is needed by every Vaadin portlet to control the creation of the UI elements.

So, let's review some of the code.

The UserDetailComponent

The UserDetailComponent is the java class that implements the interface shown above.  Below is the class constructor:

public UserDetailComponent(UsersUI uui) {
   // Invoke the Vaadin IDE code to build the widget heirarchy from the visual design.

   // set the initial values

   // also need to clear the portrait, initialize it to the basic male portrait.
   String maleUrl = UserConstants.getPortraitURL(uui.getThemeDisplay().getPathImage(), true, 0);

   // set the url as the source for the user portrait.
   userPortrait.setSource(new ExternalResource(maleUrl));

   // change the back button style to a link.

   // add the back link listener.
   backLink.addClickListener(new Button.ClickListener() {
      public void buttonClick(Button.ClickEvent clickEvent) {
         // get the ui object
         UsersUI uui = (UsersUI) getUI();

         // invoke our little switch method.

The Vaadin IDE-generated code is invoked to initialize the view per the visual design.  The Labels are updated to clear out the initial values.  

The userPortrait is an Embedded component that will be used to show the user portrait; if the user doesn't have a portrait, the basic male portrait will be used, and that's what we initialize the value to.  Using this type of component, we will be able to show the real user portrait the user might have loaded to their profile.

The style of the Back button is changed to a link, basically it will look like a hyperlink.  A click listener is also added to deal with clicks on the link.  Inside the click listener, we get the UI instance the component is bound to (our UsersUI instance) and the switchToListView()  method is invoked to handle the switch.

In Vaadin, the UI instance is accessable to every component that is added to the heirarchy.  This makes the class a great extension point to add utility methods or manage navigation.

When switching to the detail view, the component needs to update with information for the user.  Here's the method:

 * updateFromUser: Updates the screen elements for the given user id.
 * @param uId User id to update the view for.
public void updateFromUser(final long uId) {
   User user = null;

   try {
      // try to get the user given the uId...
      user = UserLocalServiceUtil.fetchUser(uId);
   } catch (SystemException e) {
      logger.error("Error fetching user " + uId + ": " + e.getMessage(), e);

   UsersUI uui = (UsersUI) getUI();

   if (user == null) {
      // we could not get a user record.  Reset all fields and return.

      // also need to clear the portrait
      String maleUrl = UserConstants.getPortraitURL(uui.getThemeDisplay().getPathImage(), true, 0);

      userPortrait.setSource(new ExternalResource(maleUrl));


   // set the labels from the values for the user.

   // also need to update the portrait.
   String portUrl = null;

   try {
      // get the portrait url for this user
      portUrl = user.getPortraitURL(uui.getThemeDisplay());
   } catch (PortalException e) {
      logger.error("Error getting user portrait url: " + e.getMessage(), e);
   } catch (SystemException e) {
      logger.error("Error getting user portrait url: " + e.getMessage(), e);

   if (StringUtils.isBlank(portUrl)) {
      // don't have a url, default to the male portrait
      portUrl = UserConstants.getPortraitURL(uui.getThemeDisplay().getPathImage(), true, 0);

   // update the portrait
   userPortrait.setSource(new ExternalResource(portUrl));

The comments here are self explanatory.

The line for getting the portrait URL for the user shows a call to a utility method exposed in the UsersUI class, the getThemeDisplay() method.  This method does what it says, it returns the current ThemeDisplay instance that is needed to get the portrait URL.  This method will come up later.

The UserListComponent

The UserListComponent is used to display the list of Liferay users.  It too was laid out using the Vaadin IDE in Eclipse, and that code was used in Intellij as the foundation for the class.  I just had to add the code to initialize the table:

public UserListComponent() {

   // This container, based on the LazyPagedContainer, encapsulates the access to the UserLocalServiceUtil
   // class and it's methods to get to the users.
   userContainer = new LazyUserContainer();

   // do not allow row selection

   // set the container as the data source for the users table.

   // we want name, email, and screen name to be a link to click to the detail page, so we will add them
   // as extra columns that are buttons.
   users.addContainerProperty(FIELD_FULLNAME, Button.class, null, NAME, null, null);
   users.addContainerProperty(FIELD_EMAILADDRESS, Button.class, null, EMAILADDRESS, null, null);
   users.addContainerProperty(FIELD_SCREENNAME, Button.class, null, SCREENNAME, null, null);

   // Since those columns will be buttons, they need to be generated.  This generator will be used
   // to generate the column objects (since they are not a natural member of the User class).
   userColumnGenerator = new UserColumnGenerator();

   // Add the generated columns.
   users.addGeneratedColumn(FIELD_FULLNAME, userColumnGenerator);
   users.addGeneratedColumn(FIELD_EMAILADDRESS, userColumnGenerator);
   users.addGeneratedColumn(FIELD_SCREENNAME, userColumnGenerator);

   // add our visible columns so only the generated are used.
   // this will leave the other members of the User class outside of it.
   users.setVisibleColumns(new Object[] {FIELD_FULLNAME, FIELD_EMAILADDRESS, FIELD_SCREENNAME});

   // refresh the rows 

The LiferayUsersComponent

The LiferayUsersComponent manages the tab widget with our two views as tab pages (the tabs themselves are hidden).  This component was also laid out using the Vaadin IDE in Eclipse, and the generated code was copied to Intellij to edit.  I didn't really change any code in this class, however, I just added two utility methods for switching to selected tabs:

 * switchToListView: Switches to the list view tab.
public void switchToListView() {
   // choose the list tab.

 * switchToDetailView: Switches to the detail view tab.
 * @param userId The user id to display details for.
public void switchToDetailView(final long userId) {
   // choose the details tab...

   // update the detail view for the selected user.

The UsersUI Class

The UsersUI class is not generated by the Vaadin IDE, you have to create this yourself.  Since the UsersUI class is pretty small, it will be presented in whole:

package com.dnebinger.liferay.vaadin.sample;

import com.liferay.portal.kernel.util.WebKeys;
import com.liferay.portal.theme.ThemeDisplay;
import com.vaadin.annotations.Theme;
import com.vaadin.server.VaadinPortlet;
import com.vaadin.server.VaadinPortletService;
import com.vaadin.server.VaadinPortletSession;
import com.vaadin.server.VaadinRequest;
import com.vaadin.ui.TabSheet;
import com.vaadin.ui.UI;
import com.vaadin.ui.VerticalLayout;

import javax.portlet.PortletRequest;

 * class UsersUI: Simple UI class to demonstrate Vaadin in the portal.  Highly commented for Liferay developers.
 * The UI extension class is the main entry point for your Vaadin portlet.  It is here that you will create your initial UI.
 * @version 1.0
 * @author dnebinger

// Use the standard Liferay theme for the widgets.
public class UsersUI extends UI {

   private VerticalLayout mainLayout;

   private LiferayUsersComponent usersComponent;

    * init: The extension point, define the initial UI for the interface.
    * @param vaadinRequest The initial request which is used to initialize the display.
   protected void init(final VaadinRequest vaadinRequest) {
      // create the main vertical layout
      mainLayout = new VerticalLayout();

      // give it a margin and space the internal components.

      // set the layout as the content area.

      // In the portal, the main widget cannot have an indeterminate height or it just won't render.  There's a number
      // of things going on between the Liferay JS, the Liferay CSS, and the GWT and Vaadin.  There is a bug open on
      // Vaadin, but until it is resolved it's best to come up with a reasonable height and set it.  Note this is just
      // an initial height to get it to render, there are corresponding things that can be done to update the height
      // later on...

      // create the users component, the component that has the (hidden) tabs.
      usersComponent = new LiferayUsersComponent(this);

      // add to the page.

      // switch to the list view for the initial view.

    * switchToListView: Utility method to switch to the list view.
   public void switchToListView() {

    * switchToDetailView: Utility method to switch to the detail view.
    * @param userId The user id to switch to.
   public void switchToDetailView(final long userId) {

    * getThemeDisplay: Returns the current ThemeDisplay instance.
    * @return ThemeDisplay The found instance.
   public ThemeDisplay getThemeDisplay() {

      ThemeDisplay td = null;

      // okay, the theme display is actually a request attribute, so we just need to get there...

      // start by getting the current portlet request
      PortletRequest portletRequest = VaadinPortletService.getCurrentPortletRequest();

      // get the ThemeDisplay instance from the request attributes
      td = (ThemeDisplay) portletRequest.getAttribute(WebKeys.THEME_DISPLAY);

      // return the instance.
      return td;

A couple of notes on this class...

We start with the @Theme annotation.  This informs Vaadin that the given Vaadin theme should be used for the UI and all of it's components.  Note this is the Vaadin theme, it is not a Liferay theme.  To see what Vaadin themes are available, you can use the Vaadin 7 Control Panel and use the Themes tab:

Vaadin Themes

This shows the list of Vaadin themes available for your Vaadin portlets.  Note that the liferay theme here does not mean the actual Liferay theme, it's actually a clone of the Liferay Classic theme in the form of a Vaadin theme (blue buttons, etc.).

The UsersUI has the two switching utility methods, these are just pass thru to the component with the tabs, but since they are in the UsersUI class they are available to all components in the app.

Finally there is the implementation of the getThemeDisplay() method.  This method accesses the current PortletRequest instance to extract the ThemeDisplay instance from the attributes.  Nothing magic here, but it is a useful routine to keep around.


After building and deploying the new portlet and dropping it in a page, you can see the results.

Here's the list view showing all active users:

Users Listing

And when you click on a user, you switch to the detail view:

Detail View

So I know what you're thinking - yuck.  It looks terrible.  Spacing is all weird, it's not at all colorful, it is just bland and boring.

And you're absolutely right.  But that is, of course, fixable.  I laid this thing out in a few hours, got the portlet working to the point where I could write this blog.  I did not spend any real time making it pretty, dealing with sizing of the view, etc.  But in a few additional hours, I could make it look pretty, make it look fresh and fine on a page.

The part that you don't see, the part that stands out - this thing rocks.  It is a full AJAX portlet.  Switching between the tabs is done entirely with JavaScript, there are no full page refreshes taking place.  I don't know of any other framework that is going to allow you to create a portlet like this in such a short amount of time that is all AJAX in the browser.


I hope this has been a useful introduction to Vaadin portlets.  It really doesn't do Vaadin justice, IMHO.  Like I said, the rendered views look pretty boring right now.  It doesn't take advantage of all of the Vaadin widgets available in the standard widgetset or any of the visual widgets available as Vaadin Add Ons.  It does however demonstrate how you can code an AJAXy portlet using only Java (there was no javascript in this example, there aren't separate pages as JSP, JSF, velocity templates, etc).  And if you're building business apps (where eye candy is not as important as getting the functionality done and out the door), this portlet may look just fine to you.

I think I will come back to this portlet in a future blog entry and address how it looks.  That will give me a chance to introduce creating custom Vaadin themes, accessing browser details for sizing, and making the view look good.

I have loaded the project into my own github account, you can access it from here:  Feel free to clone it, fork it, modify as you'd like.  Heck, I might even take pull requests if I get any.

If you have the Vaadin 7 Control Panel installed and you've deployed the LazyPagedContainer Add On, you can download and deploy the vaadin-sample-portlet-1.0-SNAPSHOT.war file directly from this blog.

Adding a Vaadin Add On to the Shared Environment

General Blogs February 2, 2015 By David H Nebinger


So Vaadin provides a core set of widgets, standard widgets that you'd find in any web framework such as radio buttons, buttons, links and text input fields.

But like most other frameworks, we as developers want a richer toolset of widgets that go beyond the standard set, usually to encapsulate some bit of a control which is obviously self contained.

While other frameworks use their own methods for adding components to the standard toolset, Vaadin has the Add On.

Add Ons

Vaadin Add Ons are commercial and/or open source widgets that provide functionality beyond what is implemented in the standard core.

As an example, here's a few useful Add Ons from the full list available at Vaadin AddOn Directory:

  • Lazy Paged Container - A specialized container to support paged retrieves to the database, a useful base for adapting Vaadin to Liferay Service Builder APIs.
  • AceEditor - A rich text editor control for Vaadin.
  • OSGiMaskedTextField - A text field which supports a mask to limit input, i.e. "(###) ###-####" for a phone number.
  • And many more...

Seriously, there are many more.  At the time of this writing, there are 305 Add Ons available for Vaadin 7.

Honestly most of these I've never used, never looked at, and likely will never use.  But it is kinda reassuring that, should the need arise, I may be able to find a missing widget in the form of an Add On from the Vaadin Directory.

Add Ons, Vaadin and Liferay

Finding an Add On that you'd like to use is merely the initial step.  After the decision is made, well then you have to figure out how to use it.

This was probably the one thing that I struggled with for Vaadin and Liferay.  I could see what the Add Ons were, I could see some that I wanted to use, but for the life of me I couldn't figure out how to take the next steps., which focuses on how you do things for servlets, well they were very helpful in telling you that you have to include the Add On when you build the widgetset and even had some magical build recipes to do that.  But when you're new to Vaadin, what does all of that mean?  And how does that info, the info that targets building servlets, how does that info apply in the portal?

So let's start with a basic premise - using Add Ons is really easy, and it can be done in Liferay in just a couple of steps.  But let's tackle some of the internals before we get to the steps...

So in Vaadin, the "widgetset" or the "compiled widgetset" is really just the sum total of compiled javascript (java compiled into javascript by GWT) that is bundled together and available for the Vaadin runtime in the browser.  So if you want to use an Add On, well then it has to be "included when you compile the widgetset", or basically it needs to be included in the process that translates java into javascript and bundles it to be available for the Vaadin browser runtime.

A corollary to that, if your Add On is not included in the compiled widgetset, even if you include the jar in your WEB-INF/lib directory, it will not be rendered in the browser because the javascript is not part of the bundle.

Before digging into the steps on how to use an Add On that this blog post is going to cover, I want to take a moment to discuss the two types of Vaadin environments in Liferay.

Vaadin actually supports developing portlets in two environments - a standalone environment and the shared environment.

In the Vaadin standalone environment, you actually build a complete Vaadin environment into your portlet.  You get the Vaadin themes, the Vaadin browser runtime (loaded by your portlet into the browser), your own compiled widgetset, etc.  This can be an easy way to create a Vaadin 7 portlet because it is totally self-contained.  My issue with this path?  Well if you are going to embrace Vaadin for your portlet development, it's likely that you're going to have a number of Vaadin portlets and possibly you're going to end up with two or more Vaadin portlets on a page.  So when this happens, because each portlet was created using the Vaadin standalone environments, you're increasing the browser resource usage to handle them - increasing memory usage, increasing bandwidth usage, etc.  Before you know it, you can have a big problem on your hands that will take you awhile to straighten out.  Also with the standalone environment, each portlet can use a different version of Vaadin; imagine trying to figure out why the browser might have issues running a portlet using 7.2.6 and another running 7.2.7 side by side?

The Vaadin shared environment was the initial Vaadin environment supported under Liferay.  In the Vaadin shared environment, the Liferay application hosts the only set of themes, the Vaadin browser runtime, the compiled widgetset, etc.  In the shared environment, there is one version of Vaadin used in the portal.  In the shared environment, the impact to the browser is greatly reduced and all portlets are consistent in the use of the same Vaadin version.

IMHO, the shared environment is the right direction, especially if you're going to be making multiple Vaadin portlets.

Using Add Ons in the Shared Environment

If you're using the Vaadin shared environment, you're using the Vaadin 7 Control Panel.  The Vaadin 7 Control Panel makes using add ons in Liferay a snap.

So let's break down the steps to get ready to use an Add On.  We're going to use the x Add On.  Download the Add On and save it somewhere locally on your system, then point your browser at your Liferay environment, log in as an administrator, go to the control panel to the Configuration section and choose the Vaadin 7 Control Panel.

From the navigation on the right side, select the Add On link to get the following view:

 Add Ons View

On the lower left corner, click the "Choose File" button to select the Add On jar file to upload: (the dialog will vary based on operating system)

Select Jar

Click on the "Upload Add-On" button to start the upload:

Before the upload is complete, you are presented with a confirmation page that provides details on the Add On.  Click the "Yes" button to finish the deploy or "No" to cancel the deploy:

Note: Some Add-Ons do not contain a widget definition.  This usually indicates the Add On is a non-visual or server-side extension.  The Lazy Paged Container has a definition of code for building a lazy reference to windowed data retrieved on demand (this is a useful class to manage retrieval of Liferay Service Builder data), but it has no visual implementation.

After approving the Add On deployment, you must check the Add On and then click the "Compile WidgetSet" button to rebuild the widgetset including your Add On(s):

As stated earlier, compiling the widgetset includes the necessary javascript for rendering Add Ons correctly in the browser.

After compiling the widgetset (click the "Done" button to finish the compile process), you'll end up on the Overview page.  The Overview page shows all of the Add Ons that are currently compiled into the widgetset:

Overview Page

At this point the Add On is available in the shared environment and your developers can leverage the Add On in their Vaadin portlets.  Don't worry, a blog post for doing this is on the way, will get it out as soon as I can.

A final note for all of you cluster admins - you'll need to repeat these steps on each node in your cluster.  Yes, I know, this is a total PITA, but Liferay doesn't have much of a mechanism to synchronize these kinds of things across the cluster.  Sure, there is some messaging which could help, but the Add Ons can be too large to push around the cluster as messages.  You're left to deploying Add Ons to the nodes in the cluster manually.  The Add Ons should be deployed to all nodes in the cluster (so they can all render the Vaadin portlets correctly).


Upgrading to Vaadin 7 in Liferay 6

General Blogs January 26, 2015 By David H Nebinger

Liferay ships with a pretty old copy of Vaadin 6, but most documentation and examples out now are for Vaadin 7.  It's pretty easy to upgrade the shared Vaadin environment to Vaadin 7, as simple as installing the Vaadin 7 Control Panel from the Marketplace.

When the Vaadin 7 Control Panel is installed, it will purge Vaadin 6 from the Liferay environment and copy an initial Vaadin 7.2.7 into the Liferay environment.

From there, you can use the Vaadin 7 Control Panel to upgrade/downgrade to another Vaadin 7 version.

Coming Soon: Vaadin 7 Control Panel

General Blogs October 2, 2014 By David H Nebinger

The Vaadin 7 Control Panel is a custom control panel designed to manage the shared Vaadin environment in Liferay.

What is the shared Vaadin environment?  It is one of two modes1 for creating Vaadin portlets and refers to the shared Vaadin environment hosted within the ROOT Liferay web application (under Vaadin 6, the shared Vaadin environment was the only supported mode).

Unfortunately managing the shared Vaadin environment has never been easy.  Vaadin requires not only jars, but also the theme and compiled widgetset files from the /html/VAADIN directory within Liferay.  Vaadin Add-Ons, deployed as Jar files, must be deployed to the ROOT/WEB-INF/lib directory (and included in the widgetset compile).  The only approved way of deploying these artifacts to Liferay is through plugins; a JSP hook can handle the theme files, but an EXT plugin is necessary for deploying the Add-On jars.

Vaadin 7 Control Panel to the Rescue!

The Vaadin 7 Control Panel solves these and other issues.  The new control panel has the following features:

  • An About Vaadin page that contains definitions for common Vaadin terms, helps those new to Vaadin understand Vaadin-speak:

About Vaadin Page

  • The Overview page summarizes everything in your shared Vaadin environment:

Overview Page

  • It is easy to change the shared Vaadin 7 version:

Change Version Page

  • Upgrade Vaadin even when the server cannot access the website:

Manual Vaadin Upload

  • The change version process reports detailed information on what is changed:

Change Version Details

  • Vaadin Add-Ons can be easily uploaded into Liferay for inclusion in the widgetset:

Add-On Upload

  • Before completing the upload, the Add-On details are presented for confirmation:

Add-On Confirmation

  • Additional dependencies for the widgetset compile can be included (these are sometimes needed for Add-Ons):

Additional Dependencies

  • Settings for the control panel can be changed inline, including memory settings used to compile the themes and widgetsets:


  • Custom themes can be created, edited, compiled, deleted, imported and exported.  The import/export feature will prove very useful to deploy themes to all nodes in a cluster, for theme promotion in corporate environments, etc.

Custom ThemesSelected Theme

  • Themes can be viewed inline.  Source files are presented in a syntax-highlighting viewer, images are previewed, and the folder hierarchy can be navigated: 

Theme Viewer

  • Custom themes can be edited inline using a syntax-highlighting editor.  Also new assets can be uploaded (images, other css files, etc.):

Custom Theme Editing

  • Compiling a theme shows detailed information about what is being done:

Theme Compiling

  • Widgetset compilation also gives detailed information:

Widgetset Compiling

Aside from these visual changes, there are a number of important non-visual changes.  The Vaadin 7 Control Panel supports localization (although currently only a language bundle will be available for English; submit your language bundle changes to for inclusion in a future release).

The Vaadin 7 Control Panel also includes a service layer.  By using the service layer, a Vaadin 7 portlet can:

  • Query for the version of the shared Vaadin 7.
  • Determine if the Valo theme is available.
  • List all available Vaadin themes.
  • List all available Vaadin Add-Ons.
  • Deploy Vaadin themes and/or Add-Ons after hot deployment.

This last item is significant.  Using the deployment features, a Vaadin plugin will be able to deploy custom themes and/or Add-Ons without requiring an administrator to set up the Vaadin environment in advance.  This opens the door for Vaadin 7 Marketplace plugins that need themes and/or Add-Ons as prerequisites, deploying them automatically so they are available when the portlet is used.  It can also be used in corporate environments to push themes and/or Add-Ons with plugins as they are promoted during development or to populate all nodes of a cluster, all without additional Liferay/Vaadin administration.

I'm really excited to get this published so it is available for the world to try.  Not just because it is a tool I've been working on for awhile, but because I see it opening doors for using Vaadin in the Marketplace as well as in the enterprise.

Vaadin is a great platform to build rich internet applications, we were just lacking a tool to pull everything together and make it easy to administrate.




1 Vaadin has been recommending a second mode for using Vaadin, a standalone mode.  In this mode, each individual portlet contains Vaadin and the theme(s) and the Add-Ons and the widgetsets, everything to be a working Vaadin portlet.  Since it is self contained, it is isolated from what goes on in the portal.  Unfortunately I believe there are some issues with this practice that have not been identified, discussed, or mitigated in any way.

For example, when you run a Vaadin portlet there is a client-side library that handles the DOM manipulation, javascript stuff, the theme application, etc.  The problem as I see it comes if you have a page with, say, 5 different Vaadin self-contained portlets.  This will lead to 5 different copies of the client-side library running in the browser!  Even if Vaadin were smart enough to handle them all in a single copy of the client side engine, what happens if one or more of the 5 were built with different versions of Vaadin, all self contained?

Same kind of issues with Add-Ons...  One plugin has version 1.0 of an addon while another has 1.1.  How does this work in the browser?  How will they be kept straight?  How do we know that there isn't some sort of bleed over from one to another?

Long story short, because of inadequate tools using the shared Vaadin environment in Liferay was a pain (some would use harsher words) and the standalone mode was seen as a way to allow developers to use Vaadin without having to figure out how to manage the shared environment.

With this new Vaadin 7 Control Panel, it will be much easier to manage the shared environment (which doesn't suffer from all of the issues the standalone mode may have) and my continuing recommendation would be to use it and avoid the standalone mode.


Vaadin Liferay Development...

General Blogs April 20, 2013 By David H Nebinger

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.



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.



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.


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.


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


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

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

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

Vaadin 6 Control Panel

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


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


Service Builder Presentation Info

General Blogs April 20, 2013 By David H Nebinger

So I received bunch of emails on Service Builder after my webinar last month...  Thought I'd write up a blog entry that will end up in the search engines and hopefully lead folks here to get to the details...

Anyway, the recorded presentation is available on the Liferay LIVE Web Events page.  You can listen to the whole presentation and watch as my demo fails during the presentation...  wink

All of the projects used for demo are actually available in this forum post in the second message of the thread.

Now for the keywords that will get you here...

The presentation covers how to do some basic Service Builder functions, but also features:

  • one-to-many relationship handling.
  • many-to-many relationship handling.
  • accessing an external (non-Liferay) database.
  • using 'fake' (non-database-backed entities) to build shared code modules using Service Builder.
  • Vaadin and Service Builder integration.


Backup/Restore a Liferay Environment

General Blogs April 20, 2013 By David H Nebinger


This page documents two important administrative functions: backing up Liferay (and restoration) and setting up a copy for development usage.

Having a backup of the database is an important issue, in order to restore the database after some sort of catastrophe. The first thing that we're going to cover is backing up the Liferay data.

Liferay uses a database for primary data storage, but also uses the filesystem to store things such as image files, documents, etc.

Since I'm using Liferay with a Mysql database running on a Linux box, these instructions will focus only on that implementation. But the details should be adaptable to any database and operating system that can host Liferay.

So first the plan: the current Mysql server is going to host a second database. The production database will be the one that the main Liferay instance will use, and the development database will be a relatively recent copy of the production database. It will be allowed to get out of sync with production because I don't want changes I'm in the middle of making overwritten just because cron thinks it is time.

Create the Development Database

Create the development database, lpdev, with the following commands:

$ mysql -u root -p mysql
mysql> create database lpdev;
mysql> grant all privileges on lpdev.* to 'lportal'@'%' with grant option;
mysql> quit;

This will create the database lpdev and give all privileges to the lportal user.

Create Backup Script

First we'll set up a backup script for the production database and data files. I'm going to create and use a local directory, /var/liferay/backups. This will centralize the backups to make them easy to use for restoration later on.

In my /etc/cron.daily folder I created a script liferay-backup.cron with the following contents:

# Back up the Liferay data.

# Get a variable to store the current date.
date=`date -I`

# Backup the liferay mysql database.
mysqldump -u lportal -p<password> lportal | bzip2 -9 -c > /var/liferay/backups/lportal-$date.sql.bz2
# Also create a backup of the Liferay data files.
tar cjf /var/liferay/backups/lportal-$ -C /opt/liferay data

You will have to change the <password> tag, replacing it with your lportal user password. NOTE: There is no space between the -p and the password. If you don't have an /etc/cron.daily directory, you can do your standard cron thing to create the backup.

This will create two files in the /var/liferay/backups directory, the sql to recreate the database and a tar file to recreate the data directory. These files are still on the same Linux box as the database and the server, so you may want to integrate the files into an off-system datastore or removable media.

This backup script runs while Liferay is still active. There is the potential of database issues (capturing partially committed data) or filesystem issues (the Lucene indices in a state of flux). Running the backup in the very early morning will help protect against this, but the potential is still there...

Recovering Liferay/Refreshing Development

The steps to recover Liferay are pretty much the same as refreshing the development environment, the only difference being the database used on the command line and the location of the data when extracted.

Restoration and refreshing should be done while Liferay is not running as changing the data on the fly could impose some serious application issues. But if you find yourself having to recover the database, it's a good bet that Liferay is not running anyway.

Recovering the Database

Recovering the database is a one-line command:

$ bzcat /var/liferay/backups/liferay-<date>.sql.bz2 | mysql -u lportal -p<password> lportal

Replace the <date> tag with a valid date from your backups. Dates will be formatted as YYYY-MM-DD. Replace the <password> tag with your lportal user password. NOTE: There is no space between the -p and the password.

Refreshing the Development Database

To refresh the development database, lpdev, you'd run the following command:

$ bzcat /var/liferay/backups/liferay-<date>.sql.bz2 | mysql -u lportal -p<password> lpdev

Do the replacements as indicated in the Recovering the Database section above.

Recovering the Data

The filesystem data has things such as the image gallery files, documents, etc. Our backup has all of these files, but you should clean out your data directory prior to expanding the backed-up data. This will ensure that you won't have any lingering data from before the restoration.

Recovery is done through the following commands:

$ /bin/rm -rf /opt/liferay/data/*
$ tar xjf /var/liferay/backups/liferay-<date>.data.tar.bz2 -C /opt/liferay

After starting Liferay, you're going to want to go to the Control Panel, Server Administration page and choose "Reindex all search indexes". This will rebuild all of the Lucene indices from the restored information in the database and the data files and leave it in a consistent state.

Refreshing the Development Data

You'll know if your local Liferay data is out of sync when you start seeing broken image tags, etc., in your development portal. To fix these kinds of issues, you'll have to refresh the development data. Since we're doing development on a Windows box, refreshing the data is a bit more complicated. Basically you're going to complete the following steps:

  1. Get the liferay-<date>.data.tar.bz2 file from your Linux box to your Windows box.
  2. Delete the contents of the c:\liferay\bundle\data directory.
  3. Expand the contents in the c:\liferay\bundle directory (Since the archive already is prefixed with the data directory, you should not expand in the data directory or you'll have c:\liferay\bundle\data\data and Liferay won't find it at startup).
  4. After starting Liferay, you're going to want to go to the Control Panel, Server Administration page and choose "Reindex all search indexes" to ensure the Lucene indices are consistent.


So now you're all set w/ your backup and recovery for Liferay. You can also refresh your development environment so that it matches production.

If you have just created your development database, you're going to want to run the Liferay backup script to create the sql and data files. Then follow the steps to refresh your development environment. Don't forget to change the database to lpdev in your file in c:\liferay\bundle\tomcat-6.0.29\webapps\ROOT\WEB-INF\classes so you access the right database in development.

Liferay and SSL

General Blogs April 20, 2013 By David H Nebinger


So I've got my Liferay site up and running under Tomcat and fronted by Apache HTTPd. The next thing I wanted to do was add an SSL certificate so that I could get it all under HTTPS...

SSL certificates, from sites like VeriSign or Thawte or Network Solutions are usually the players that come to mind when you want to get a certificate.

A quick Google search, however, yields scores of other companies that provide SSL certificates. After pricing a bunch of them, I finally settled on a certificate from GoDaddy. At $12.99 per certificate per year, it's hard to beat the price and they are handled in most browsers.

For the most part the instructions for getting a certificate on the GoDaddy site are straight-forward. There were a few hiccups along the way, mostly due to my use of the Apache Portable Runtime (APR) in conjunction with Apache HTTPd and Tomcat.

So I'm going to lay out all of the steps that I had to take in order to request the certificate, get the certificate, install the certificate in Apache and Tomcat, and finally get it all working.

Create the Certificate Signing Request

Creating the csr, or Certificate Signing Request, is a fairly simple process. Since we're getting a certificate to install into both Apache and Tomcat, you could look at two different sets of instructions, one for each server. Since I think (but do not know for sure) that getting the certificate into Tomcat is going to be the harder of the two, I elected to follow the Tomcat instructions.

To generate the csr for Tomcat, you have a number of commands to execute in the shell to create the csr file and then you have to paste the contents of the csr file into the GoDaddy form.  The GoDaddy instructions for creating the csr are here.

The first step involves creating the keystore that Tomcat will be referencing. You'll need to know where on the filesystem your keystore will be stored, because you'll eventually be pointing Tomcat to it for usage. On my Gentoo system, certificates are usually in the /etc/ssl directory, so that's where I built mine. I created the /etc/ssl/tomcat directory and then cd'd to that directory. The remainder of the shell script commands were all executed from this directory.

Creating the keystore involves running the following command:

$ keytool -keysize 2048 -genkey -alias tomcat -keyalg RSA -keystore tomcat.keystore

When you type this command, you'll be prompted with a series of questions, and the GoDaddy instructions tell you what needs to go into each field.

If you don't want to go through the prompts, a web-based form for building the command to create the keystore can be found at Note that you'll have to edit the script they generate to change the alias specified above, but otherwise the tool works quite well.

Next you need to generate the csr using the following command:

$ keytool -certreq -keyalg RSA -alias tomcat -file <your file name>.csr -keystore tomcat.keystore

Replace the <your file name> with the csr filename you want to use. It is not that important because you don't really send the file anywhere. I named mine dnebinger.csr.

The part that is missing from the GoDaddy instructions relates to whether you are using the Apache Portable Runtime (as I am). When using the APR, you will be needing the private key that is currently stored inside of the tomcat.keystore file. I couldn't find a way to extract the private key using keytool, but I did find a tool at that could do it. Download the tool and run it as instructed from the link to get the PKCS#8 format and direct it to a file. Give the file a .pem extension; I used the tool to create my dnebinger.pem file.

$ java ExportPriv /etc/ssl/tomcat/tomcat.keystore tomcat {keystore_password} > /etc/ssl/tomcat/<your file name>.pem

Cat your .csr file and copy it into the clipboard. Go to the GoDaddy form and paste in your csr. You'll then have to wait for GoDaddy to create your certificate.

Wait for Your SSL Certificate

While waiting, I did get an email from GoDaddy indicating that they could not verify that I was in control of the domain (my whois information is blocked from public consumption, thank you Network Solutions!). One option was to create a specially named html file and serve it from my Apache web server. I followed the instructions to create the html file, naming it correctly and putting the right stuff inside. Since I have Apache fronting my Liferay/Tomcat and do not have html file extensions JkUnmount'd, I had to temporarily add the JkUnmount for html files so when GoDaddy would come looking for the file I'd be able to serve it up quickly and easilly. I then went to the GoDaddy site and followed their further instructions for validating using the special file. Domain control was verified immediately, and they created the certificate.

Download Your SSL Certificates

So, next comes downloading the certificate. When downloading, you choose the type of server that you're installing the certificate into. I chose first to download the Tomcat version, then I chose to download the Apache version. The certificates are downloaded in zip format, you'll need to expand them. I extracted the Tomcat version to /etc/ssl/tomcat and the Apache one to /etc/ssl/apache.

Setup Tomcat to Use the Certificate

You don't really have to follow the Tomcat instructions for installing the certificate, it is actually quite easy. Since I'm using APR, I don't need to install the certificate into the keystore, but I do need the private key.

Using the certificate in Tomcat is a matter of editing the /opt/liferay/tomcat/conf/server.xml file (use whatever path is appropriate for your local environment). Find the <Connector /> tag for port 8443 and add the following attributes:

SSLPass="<your keystore password>"

And change the attribute for SSLProtocol so it says "TLSv1".

Setup Apache to Use the Certificate

Setting up Apache simply requires following GoDaddy's instructions. For my Gentoo system, I had to edit /etc/apache2/vhost.d/00_default_ssl_vhost.conf. For the SSLCertificateChainFile entry, they're referring to the gd_bundle.crt file that was part of the downloaded zip. The SSLCertificateKeyFile entry refers to the private key file that was created, in my case it is dnebinger.pem.

Setup Liferay to Use HTTPS

Since you've got this new certificate, you're going to want Liferay to use it. You need to edit your /opt/liferay/tomcat/webapps/ROOT/WEB-INF/classes/ file and add the following entries:


At this point everything should be configured and ready to go. Restart your Liferay/Tomcat and Apache servers, and then you can hit them using either the http or https urls. Since we've configured Liferay to prefer https, you should see that when you use the http url you will eventually be redirected to the https url.


Fronting Liferay Tomcat with Apache HTTPd daemon

General Blogs April 20, 2013 By David H Nebinger


So here's my situation...

I've got a Gentoo Linux server sitting around that I wanted to get Liferay 6.0.6 up and running on. Although this blog will cover the setup I did for my Gentoo box, for the most part you should be able to adapt what I've done for your Linux box. Heck, a lot of this will probably work on a Windows system too, but you're on your own as far as that goes...

Installing Dependencies and the Liferay Tomcat Bundle

My system already has the Java SDK, OpenSSL, and other dependent software installed, so I'm not going to rehash that installation and setup. Suffice it to say that you may find yourself installing some missing components along the way to satisfy dependencies...

Gentoo makes installation pretty easy for all of the components that I needed. Specifically I issued the following command:

$ emerge www-servers/apache dev-libs/apr dev-libs/apr-util www-apache/mod_jk

So that installs the basic software for Apache HTTPd version 2.2.17, but doesn't complete the configuration for us.

Next I downloaded the Liferay 6.0.6/Tomcat bundle in preparation for installation.

Now you might be asking yourselves why I didn't install Tomcat using Gentoo's emerge command and then install Liferay into Gentoo's Tomcat. The reason is that Gentoo's Tomcat actually gets installed to many different directories and doesn't retain the 'all in one directory' setup that's pretty standard w/ Tomcat installs. The tomcat/logs directory ends up over in /var/log, the tomcat/temp directory ends up over in /var/tmp, the tomcat/bin, tomcat/lib, and tomcat/webapps directories end up in /usr/share/tomcat-6, and tomcat/conf ends up in /etc. From a Linux standards perspective, this reorganization makes total sense. Knowing all of the reconfiguration I'd be doing in order to get Liferay up and running in this setup seems to be more trouble than it's worth, at least in the short term. Who knows, maybe if I get some time I'll explore what is involved in doing it the Gentoo way, but for now I've decided to skip it...

Instead I expanded the Liferay 6.0.6 Tomcat bundle to /opt, with the final installation path as /opt/liferay-portal-6.0.6. To make upgrading easier, I created a symbolic link as /opt/liferay using the following command:

$ ln -s /opt/liferay-portal-6.0.6 /opt/liferay

So the path for tomcat is now /opt/liferay/tomcat-6.0.29, and I created another symlink for that as /opt/liferay/tomcat.

The first thing I did was delete the provided JRE that is part of the bundle. This makes the and scripts unhappy as they want to use that JRE, so I had to edit them to use my installed Java environment. I also took the opportunity to hard code the CATALINA_HOME environment variable and tweak the Java command line arguments for memory handling, timezone, etc.

From here you'll want to skip over to and use their documentation to get your database defined, mail server changes done, and fix up your files.

At the end of all of this configuration, I could start up Tomcat and hit Liferay by going to Tomcat's port 8080 in order to verify that it was up and running.

So next we have to worry about setting up Apache so that it can front Tomcat. A lot of folks have trouble doing this (you'll see a lot of questions and stuff when you search your favorite search engine). I have to admit that I had to go back and forth tweaking the files until I got it all right...

So now I'm going to be referring to the Apache config files, specifically as initially installed in my Gentoo system. The file paths will probably be different on your system, but the content of the changes should basically be the same...

Configure mod_jk

Gentoo installed mod_jk as part of our previous emerge command, but we need to enable it so Apache will use it when it is running. So we have to edit /etc/conf.d/apache2 and find the line with the APACHE2_OPTS defined. At the end of the line (but still within the quotes), add -D JK. This will enable the loading of the mod_jk when Apache starts up.

The default configuration for mod_jk as installed in Gentoo is pretty complete and shouldn't require any significant editing. The only change I had to make to /etc/apache2/modules.d/88_mod_jk.conf was to change the only uncommented JkMount line so it read:

JkMount /* ajp13

I also changed the JkAutoAlias so that it pointed to /opt/liferay/tomcat/webapps, but honestly I don't know if it was really necessary or not.

Now, the one thing you'll see going forward is that I actually have the JkMount thing in another file. This change was the most obvious one (I mean, the default Gentoo file already had a JkMount here), but it didn't work the first time I started Apache up. So there will be another place in this blog where the JkMount will come up again, and if you do them all you should have the same success that I had.

Gentoo's workers file is /etc/apache2/ It's got a lot of comments in it, but basically you should end up w/ the following:


The ajp13 is actually going to be our Liferay/Tomcat guy. Perhaps I should have changed it to, say, liferay, but I didn't feel that I wanted to make such sweeping changes to Gentoo's default config.

I said the JkMount would come up again, and here it is. I had to modify the /etc/apache2/vhosts.d/default_vhost.include file, and I added the following:

<IfModule jk_module>
  JkMount /* ajp13

This change applies the JkMount to the default virtual host, and was necessary for Apache to pass the requests through to Liferay.

After these changes were made, I could fire up Apache and hit the regular port 80 of Apache and it passed the requests through to Tomcat, and it was all working great!

Have Apache Serve Liferay Static Content

The best reason to front Liferay/Tomcat with Apache is to let Apache handle the serving of the static content (images, stylesheets, etc) and let Tomcat deal w/ the dynamic content.

To do this, you're going to have to do some directory copying... First copy the /opt/liferay/tomcat/webapps/ROOT/html directory to Apache's htdocs directory, /var/www/localhost/htdocs in my case. You should also copy all of the other webapps directories (all except for ROOT) to the htdocs directory. By copying all of these directories, any incoming requests for static content will be handled by Apache rather than Tomcat.

NOTE: As you redeploy your portlets, themes, etc. to Liferay, you should also copy the directories over to the htdocs directory, otherwise Apache might serve an older version of the file(s).

For Apache to handle static files, you need to go back to the /etc/apache2/vhosts.d/default_vhost.include file and add some lines just below the JkMount line you added earlier. You'll end up with the following:

<IfModule jk_module>
  JkMount /* ajp13

  JkUnmount /*.jpg ajp13
  JkUnmount /*.jpeg ajp13
  JkUnmount /*.gif ajp13
  JkUnmount /*.png ajp13
  JkUnmount /*.ico ajp13
  JkUnmount /*.css ajp13
  JkUnmount /*.js ajp13

By using JkUnmount, you're indicating to Apache that it should handle requests with the given extension(s) rather than passing them through to Tomcat.

The one obvious extension that is missing from the above is the .html extension. Since the servlet mapping mechanism in a web application can map .html extensions to a servlet, adding this extension might not give you the result you're expecting. The way I figure it, it's better to let Tomcat serve the single html file (if it is static) rather than break some servlet or portlet functionality, but it is really just a matter of research in the various web.xml files to see if you have any servlet mappings expecting .html extensions. If you don't have any such mappings (now or in the future), you can add the extension as a JkUnmount and let Apache handle them. If you do have the mappings, expect to have the mappings, or just don't want to do the research, then leaving the JkUnmount out for this extension is the safest bet.

Since we're talking about JkUnmounts, if you have other directories in your htdocs folder that Apache should always handle, then add them as JkUnmounts. For example, say I have a javadocs directory in my htdocs folder and I need Apache to handle it, I'd add the following line:

  JkUnmount /javadocs/* ajp13

Setup Liferay To Use Apache

The final step involves editing your /opt/liferay/tomcat/webapps/ROOT/WEB-INF/classes/ file to include the following:


This ensures that Liferay will know that it is operating behind Apache HTTPd and will handle redirects correctly.

That's all there is to it. The fact that you're seeing this on port 80 rather than 8080 is proof that these instructions work!

My First Liferay Blog...

General Blogs April 16, 2013 By David H Nebinger

I was going to take a queue from Jelmer and start with just a test blog post, but don't want to take the wind out of his sails...  Must say, though, that your blog post did make me laugh Jelmer!  laugh

Instead, I'm going to lead w/ my blogging plans...

First, I've got a handful of blog postings I had put together about HTTPS/Apache Httpd/Tomcat/Liferay that I'm going to restore here.  Had them up on my home Linux box, but as it's my home server I end up making changes and playing with different versions of Liferay, so although the blog entries had value, they're not up anymore.  Pulling them over here will give them a little more permanence and keep them safe from my Linux server hacking...

Then comes the fun stuff, I'm going to dive into Vaadin portlet development under Liferay.  I'll cover the dev environment setup, the must-have Vaadin Control Panel, then maybe move into some actual Vaadin portlet development...

Oh, boy, I just can't wait...

Showing 61 - 78 of 78 results.
Items 20
of 4