Adding a Vaadin Add On to the Shared Environment


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