--- 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 <>. 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 <> 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"] ---- <?xml version="1.0" encoding="UTF-8" standalone="no"?> <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"> <portlet> <portlet-name>[replaceable]##Portlet Example portlet##</portlet-name> <display-name>[replaceable]##Vaadin Portlet Example##</display-name> <!-- Map portlet to a servlet. --> <portlet-class> com.vaadin.server.VaadinPortlet </portlet-class> <init-param> <name>UI</name> <!-- The application class with package name. --> <value>[replaceable]##com.example.myportlet.MyportletUI##</value> </init-param> <!-- Supported portlet modes and content types. --> <supports> <mime-type>text/html</mime-type> <portlet-mode>view</portlet-mode> <portlet-mode>edit</portlet-mode> <portlet-mode>help</portlet-mode> </supports> <!-- Not always required but Liferay requires these. --> <portlet-info> <title>[replaceable]##Vaadin Portlet Example##</title> <short-title>[replaceable]##Portlet Example##</short-title> </portlet-info> </portlet> </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. [[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"] ---- <?xml version="1.0" encoding="UTF-8"?> <!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"> <liferay-portlet-app> <portlet> <!-- Matches definition in portlet.xml. --> <!-- Note: Must not be the same as servlet name. --> <portlet-name>[replaceable]##Portlet Example portlet##</portlet-name> <instanceable>true</instanceable> <ajaxable>false</ajaxable> </portlet> </liferay-portlet-app> ---- 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]] .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: ---- ... widgetset com.vaadin.portal.PortalDefaultWidgetSet ... ---- 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 <> 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 <>, 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.