Deploying to a Portal

To deploy a portlet WAR in a portal, you need to provide a portlet.xml descriptor specified in the Java Portlet API 2.0 standard (JSR-286). In addition, you may need to include possible portal vendor specific deployment descriptors. The ones required by Liferay are described below.

Deploying a Vaadin UI as a portlet is essentially just as easy as deploying a regular application to an application server. You do not need to make any changes to the UI itself, but only the following:

  • Application packaged as a WAR

    • WEB-INF/portlet.xml descriptor

    • WEB-INF/liferay-portlet.xml descriptor for Liferay

    • WEB-INF/liferay-display.xml descriptor for Liferay

    • WEB-INF/liferay-plugin-package.properties for Liferay

  • Widget set installed to portal (optional)

  • Themes installed to portal (optional)

  • Vaadin libraries installed to portal (optional)

  • Portal configuration settings (optional)

The Vaadin Plugin for Eclipse creates these files for you, when you create a portlet project as described in “Creating a Generic Portlet in Eclipse”.

Installing the widget set and themes to the portal is required for running two or more Vaadin portlets simultaneously in a single portal page. As this situation occurs quite easily, we recommend installing them in any case. Instructions for Liferay are given in “Developing Vaadin Portlets for Liferay” and the procedure is similar for other portals.

In addition to the Vaadin libraries, you will need to have the portlet.jar in your project classpath. However, notice that you must not put the portlet.jar in the same WEB-INF/lib directory as the Vaadin JAR or otherwise include it in the WAR to be deployed, because it would create a conflict with the internal portlet library of the portal. The conflict would cause errors such as “ ClassCastException: …VaadinPortlet cannot be cast to javax.portlet.Portlet”.

Portlet Deployment Descriptor

The portlet WAR must include a portlet descriptor located at WEB-INF/portlet.xml. A portlet definition includes the portlet name, mapping to a servlet, modes supported by the portlet, and other configuration. Below is an example of a simple portlet definition in portlet.xml descriptor.

  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <portlet-app
  3.   xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
  4.   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  5.   version="2.0"
  6.   xsi:schemaLocation=
  7.     "http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd
  8.      http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">
  10.   <portlet>
  11.     <portlet-name>Portlet Example portlet</portlet-name>
  12.     <display-name>Vaadin Portlet Example</display-name>
  14.     <!-- Map portlet to a servlet. -->
  15.     <portlet-class>
  16.       com.vaadin.server.VaadinPortlet
  17.     </portlet-class>
  18.     <init-param>
  19.       <name>UI</name>
  21.       <!-- The application class with package name. -->
  22.       <value>com.example.myportlet.MyportletUI</value>
  23.     </init-param>
  25.     <!-- Supported portlet modes and content types. -->
  26.     <supports>
  27.       <mime-type>text/html</mime-type>
  28.       <portlet-mode>view</portlet-mode>
  29.       <portlet-mode>edit</portlet-mode>
  30.       <portlet-mode>help</portlet-mode>
  31.     </supports>
  33.     <!-- Not always required but Liferay requires these. -->
  34.     <portlet-info>
  35.       <title>Vaadin Portlet Example</title>
  36.       <short-title>Portlet Example</short-title>
  37.     </portlet-info>
  38.   </portlet>
  39. </portlet-app>

The mode definitions enable the corresponding portlet controls in the portal. The portlet controls allow changing the mode of the portlet, as described later.

Liferay Portlet Descriptor

Liferay requires a special liferay-portlet.xml descriptor file that defines Liferay-specific parameters. Especially, Vaadin portlets must be defined as “ instanceable“, but not “ ajaxable“.

Below is an example descriptor for the earlier portlet example:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE liferay-portlet-app PUBLIC
  3.   "-//Liferay//DTD Portlet Application 4.3.0//EN"
  4.   "http://www.liferay.com/dtd/liferay-portlet-app_4_3_0.dtd">
  6. <liferay-portlet-app>
  7.     <portlet>
  8.         <!-- Matches definition in portlet.xml.          -->
  9.         <!-- Note: Must not be the same as servlet name. -->
  10.         <portlet-name>Portlet Example portlet</portlet-name>
  12.         <instanceable>true</instanceable>
  13.         <ajaxable>false</ajaxable>
  14.     </portlet>
  15. </liferay-portlet-app>

See Liferay documentation for further details on the liferay-portlet.xml deployment descriptor.

Liferay Display Descriptor

The WEB-INF/liferay-display.xml file defines the portlet category under which portlets are located in the Add Application window in Liferay. Without this definition, portlets will be organized under the “Undefined” category.

The following display configuration, which is included in the demo WAR, puts the Vaadin portlets under the “Vaadin” category, as shown in Portlet Categories in Add Application Window.

  1. <?xml version="1.0"?>
  2. <!DOCTYPE display PUBLIC
  3.   "-//Liferay//DTD Display 4.0.0//EN"
  4.   "http://www.liferay.com/dtd/liferay-display_4_0_0.dtd">
  6. <display>
  7.     <category name="Vaadin">
  8.         <portlet id="Portlet Example portlet" />
  9.     </category>
  10. </display>

liferay display hi

Portlet Categories in Add Application Window

See Liferay documentation for further details on how to configure the categories in the liferay-display.xml deployment descriptor.

Liferay Plugin Package Properties

The liferay-plugin-package.properties file defines a number of settings for the portlet, most importantly the Vaadin JAR to be used.

  1. name=Portlet Example portlet
  2. short-description=myportlet
  3. module-group-id=Vaadin
  4. module-incremental-version=1
  5. #change-log=
  6. #page-uri=
  7. #author=
  8. license=Proprietary
  9. portal-dependency-jars=\
  10.     vaadin.jar

name

The plugin name must match the portlet name.

short-description

A short description of the plugin. This is by default the project name.

module-group-id

The application group, same as the category id defined in liferay-display.xml.

license

The plugin license type; “proprietary” by default.

portal-dependency-jars

The JAR libraries on which this portlet depends. This should have value vaadin.jar, unless you need to use a specific version. The JAR must be installed in the portal, for example, in Liferay bundled with Tomcat to tomcat-x.x.x/webapps/ROOT/WEB-INF/lib/vaadin.jar.

Using a Single Widget Set

If you have just one Vaadin application that you ever need to run in your portal, you can just deploy the WAR as described above and that’s it. However, if you have multiple applications, especially ones that use different custom widget sets, you run into problems, because a portal window can load only a single Vaadin widget set at a time. You can solve this problem by combining all the different widget sets in your different applications into a single widget set using inheritance or composition.

For example, if using the default widget set for portlets, you should have the following for all portlets so that they will all use the same widget set:

  1. <portlet>
  2.   ...
  3.   <!-- Use the portal default widget set for all portal demos. -->
  4.   <init-param>
  5.     <name>widgetset</name>
  6.     <value>com.vaadin.portal.PortalDefaultWidgetSet</value>
  7.   </init-param>
  8.   ...

The PortalDefaultWidgetSet extends SamplerWidgetSet, which extends the DefaultWidgetSet. The DefaultWidgetSet is therefore essentially a subset of PortalDefaultWidgetSet, which contains also the widgets required by the Sampler demo. Other applications that would otherwise require only the regular DefaultWidgetSet, and do not define their own widgets, can just as well use the larger set, making them compatible with the demos. The PortalDefaultWidgetSet will also be the default Vaadin widgetset bundled in Liferay 5.3 and later.

If your portlets are contained in multiple WARs, which can happen quite typically, you need to install the widget set and theme portal-wide so that all the portlets can use them. See “Developing Vaadin Portlets for Liferay” on configuring the widget sets in the portal itself.

Building the WAR Package

To deploy the portlet, you need to build a WAR package. For production deployment, you probably want to either use Maven or an Ant script to build the package. In Eclipse, you can right-click on the project and select Export › WAR. Choose a name for the package and a target. If you have installed Vaadin in the portal as described in “Developing Vaadin Portlets for Liferay”, you should exclude all the Vaadin libraries, as well as widget set and themes from the WAR.

Deploying the WAR Package

How you actually deploy a WAR package depends on the portal. In Liferay, you simply drop it to the deploy subdirectory under the Liferay installation directory. The deployment depends on the application server under which Liferay runs; for example, if you use Liferay bundled with Tomcat, you will find the extracted package in the webapps directory under the Tomcat installation directory included in Liferay.