Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 305 insertions, 0 deletions

diff --git a/documentation/portal/portal-deployment.asciidoc b/documentation/portal/portal-deployment.asciidoc
new file mode 100644
index 0000000000..dc3cf49e00
--- /dev/null
+++ b/documentation/portal/portal-deployment.asciidoc
@@ -0,0 +1,305 @@
+---
+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
+
+[options="compact"]
+** [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
+<<dummy/../../../framework/portal/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
+<<dummy/../../../framework/portal/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="normal"]
+----
+&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;**Portlet Example portlet**&lt;/portlet-name&gt;
+    &lt;display-name&gt;**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;**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;**Vaadin Portlet Example**&lt;/title&gt;
+      &lt;short-title&gt;**Portlet Example**&lt;/short-title&gt;
+    &lt;/portlet-info&gt;
+  &lt;/portlet&gt;
+&lt;/portlet-app&gt;
+----
+Listing supported portlet modes in [filename]#portlet.xml# enables the
+corresponding portlet controls in the portal user interface that allow changing
+the mode, 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;**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[]
+
+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=**Portlet Example portlet**
+short-description=**myportlet**
+module-group-id=**Vaadin**
+module-incremental-version=1
+#change-log=
+#page-uri=
+#author=
+license=Proprietary
+portal-dependency-jars=\
+    **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.
+
+
+
+