123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291 |
- ---
- title: Deploying to a Portal
- order: 5
- layout: page
- ---
-
- [[portal.deployment]]
- = Deploying to a Portal
-
- For OSGi portlets in Liferay 7, see
- <<dummy/../../../framework/portal/portal-osgi#portal.osgi.portlet,"Publishing a Portlet With OSGi">>.
- The text below applies mostly to non-OSGi portlets.
-
- 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)
-
- 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"]
- ----
- <?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>>.
-
-
- ----
- <?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.
|