path: root/documentation/portal/portal-deployment.asciidoc

---
title: Deploying to a Portal
order: 5
layout: page
---

[[portal.deployment]]
= Deploying to a Portal

To deploy a portlet WAR in a portal, you need to provide a
[filename]#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:

[options="compact"]
* Application packaged as a WAR

** [filename]#WEB-INF/portlet.xml# descriptor

** [filename]#WEB-INF/liferay-portlet.xml# descriptor for Liferay

** [filename]#WEB-INF/liferay-display.xml# descriptor for Liferay

** [filename]#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 <<portal-eclipse#portal.eclipse,"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 <<portal-liferay#portal.liferay,"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
[filename]#portlet.jar# in your project classpath. However, notice that you must
__not__ put the [filename]#portlet.jar# in the same [filename]#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 "
[literal]#++ClassCastException: ...VaadinPortlet cannot be cast to
javax.portlet.Portlet++#".

[[portal.deployment.descriptor]]
== Portlet Deployment Descriptor

The portlet WAR must include a portlet descriptor located at [filename]#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 [filename]#portlet.xml# descriptor.

[subs="verbatim,replacements,quotes"]
----
&lt;?xml version="1.0" encoding="UTF-8" standalone="no"?&gt;
&lt;portlet-app
  xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="2.0"
  xsi:schemaLocation=
    "http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd
     http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"&gt;

  &lt;portlet&gt;
    &lt;portlet-name&gt;[replaceable]##Portlet Example portlet##&lt;/portlet-name&gt;
    &lt;display-name&gt;[replaceable]##Vaadin Portlet Example##&lt;/display-name&gt;

    &lt;!-- Map portlet to a servlet. --&gt;
    &lt;portlet-class&gt;
      com.vaadin.server.VaadinPortlet
    &lt;/portlet-class&gt;
    &lt;init-param&gt;
      &lt;name&gt;UI&lt;/name&gt;

      &lt;!-- The application class with package name. --&gt;
      &lt;value&gt;[replaceable]##com.example.myportlet.MyportletUI##&lt;/value&gt;
    &lt;/init-param&gt;

    &lt;!-- Supported portlet modes and content types. --&gt;
    &lt;supports&gt;
      &lt;mime-type&gt;text/html&lt;/mime-type&gt;
      &lt;portlet-mode&gt;view&lt;/portlet-mode&gt;
      &lt;portlet-mode&gt;edit&lt;/portlet-mode&gt;
      &lt;portlet-mode&gt;help&lt;/portlet-mode&gt;
    &lt;/supports&gt;

    &lt;!-- Not always required but Liferay requires these. --&gt;
    &lt;portlet-info&gt;
      &lt;title&gt;[replaceable]##Vaadin Portlet Example##&lt;/title&gt;
      &lt;short-title&gt;[replaceable]##Portlet Example##&lt;/short-title&gt;
    &lt;/portlet-info&gt;
  &lt;/portlet&gt;
&lt;/portlet-app&gt;
----

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

[[portal.deployment.liferay]]
== Liferay Portlet Descriptor

((("Liferay", "portlet descriptor", id="term.portal.liferay.descriptor.liferay-portlet.liferay", range="startofrange")))

Liferay requires a special [filename]#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:

[subs="normal"]
----
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE liferay-portlet-app PUBLIC
  "-//Liferay//DTD Portlet Application 4.3.0//EN"
  "http://www.liferay.com/dtd/liferay-portlet-app_4_3_0.dtd"&gt;

&lt;liferay-portlet-app&gt;
    &lt;portlet&gt;
        &lt;!-- Matches definition in portlet.xml.          --&gt;
        &lt;!-- Note: Must not be the same as servlet name. --&gt;
        &lt;portlet-name&gt;[replaceable]##Portlet Example portlet##&lt;/portlet-name&gt;

        &lt;instanceable&gt;true&lt;/instanceable&gt;
        &lt;ajaxable&gt;false&lt;/ajaxable&gt;
    &lt;/portlet&gt;
&lt;/liferay-portlet-app&gt;
----
See Liferay documentation for further details on the
[filename]#liferay-portlet.xml# deployment descriptor.

(((range="endofrange", startref="term.portal.liferay.descriptor.liferay-portlet.liferay")))

[[portal.deployment.liferay-display]]
== Liferay Display Descriptor

((("[filename]#liferay-display.xml#", id="term.portal.liferay.descriptor.liferay-display", range="startofrange")))


((("Liferay", "display descriptor", id="term.portal.liferay.descriptor.liferay-display.liferay", range="startofrange")))


The [filename]#WEB-INF/liferay-display.xml# file defines the portlet category
under which portlets are located in the [guilabel]#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
<<figure.portal.liferay.descriptor.display>>.


----
<?xml version="1.0"?>
<!DOCTYPE display PUBLIC
  "-//Liferay//DTD Display 4.0.0//EN"
  "http://www.liferay.com/dtd/liferay-display_4_0_0.dtd">

<display>
    <category name="Vaadin">
        <portlet id="Portlet Example portlet" />
    </category>
</display>
----

[[figure.portal.liferay.descriptor.display]]
.Portlet Categories in Add Application Window
image::img/liferay-display-hi.png[width=60%]

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

(((range="endofrange", startref="term.portal.liferay.descriptor.liferay-display")))
(((range="endofrange", startref="term.portal.liferay.descriptor.liferay-display.liferay")))

[[portal.deployment.liferay-plugin]]
== Liferay Plugin Package Properties

((("[filename]#liferay-plugin-package.xml#", id="term.portal.liferay.descriptor.liferay-plugin", range="startofrange")))


((("Liferay", "plugin properties", id="term.portal.liferay.descriptor.liferay-plugin.liferay", range="startofrange")))


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

[subs="normal"]
----
name=[replaceable]##Portlet Example portlet##
short-description=[replaceable]##myportlet##
module-group-id=[replaceable]##Vaadin##
module-incremental-version=1
#change-log=
#page-uri=
#author=
license=Proprietary
portal-dependency-jars=\
    [replaceable]##vaadin.jar##
----
[parameter]#name#:: The plugin name must match the portlet name.

[parameter]#short-description#:: A short description of the plugin. This is by default the project name.

[parameter]#module-group-id#:: The application group, same as the category id defined in
[filename]#liferay-display.xml#.

[parameter]#license#:: The plugin license type; "proprietary" by default.

[parameter]#portal-dependency-jars#:: The JAR libraries on which this portlet depends. This should have value
[filename]#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
[filename]#tomcat-x.x.x/webapps/ROOT/WEB-INF/lib/vaadin.jar#.



(((range="endofrange", startref="term.portal.liferay.descriptor.liferay-plugin")))
(((range="endofrange", startref="term.portal.liferay.descriptor.liferay-plugin.liferay")))

[[portal.deployment.widgetset]]
== 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:


----
<portlet>
  ...
  <!-- Use the portal default widget set for all portal demos. -->
  <init-param>
    <name>widgetset</name>
    <value>com.vaadin.portal.PortalDefaultWidgetSet</value>
  </init-param>
  ...
----

The [classname]#PortalDefaultWidgetSet# extends [classname]#SamplerWidgetSet#,
which extends the [classname]#DefaultWidgetSet#. The
[classname]#DefaultWidgetSet# is therefore essentially a subset of
[classname]#PortalDefaultWidgetSet#, which contains also the widgets required by
the Sampler demo. Other applications that would otherwise require only the
regular [classname]#DefaultWidgetSet#, and do not define their own widgets, can
just as well use the larger set, making them compatible with the demos. The
[classname]#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
<<dummy/../../../framework/portal/portal-liferay#portal.liferay,"Developing
Vaadin Portlets for Liferay">> on configuring the widget sets in the portal
itself.


[[portal.deployment.war]]
== 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
<<dummy/../../../framework/portal/portal-liferay#portal.liferay,"Developing
Vaadin Portlets for Liferay">>, you should exclude all the Vaadin libraries, as
well as widget set and themes from the WAR.


[[portal.deployment.deploy]]
== Deploying the WAR Package

How you actually deploy a WAR package depends on the portal. In Liferay, you
simply drop it to the [filename]#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 [filename]#webapps# directory under the
Tomcat installation directory included in Liferay.