@@ -66,37 +66,3 @@ Alternatively, an OSGi bundle activator or an SCR Component [interfacename]#@Act | |||
---- | |||
In addition to these approaches, it is also possible to repackage all the static resources of an application to a single bundle and export the [filename]#/VAADIN# directory. This can be useful e.g. when migrating an old Vaadin OSGi application in an environment that does not support parallel deployments of multiple versions of the application. | |||
[[advanced.osgi.portlet]] | |||
== Publishing a Portlet With OSGi | |||
Publishing an OSGi portlet on Liferay 7+ can be done in two ways: using annotations or using properties. | |||
Annotating a UI class with [interfacename]#@VaadinLiferayPortletConfiguration# (available in `vaadin-liferay-integration`) and making it an OSGi service of type [classname]#UI# is the easiest way to automatically publish the UI as a portlet and configure it to use the correct static resources. | |||
[source, java] | |||
---- | |||
@Theme(MyTheme.THEME_NAME) | |||
@VaadinLiferayPortletConfiguration(name = "Vaadin.Tutorial.1", displayName = "Vaadin Tutorial App") | |||
@Component(service = UI.class) | |||
public class MyUI extends UI { | |||
... | |||
} | |||
---- | |||
Alternatively, the property [literal]#com.vaadin.osgi.liferay.portlet-ui=true# can be used when publishing a UI as an OSGi service to publish the UI as a portlet. | |||
[source, java] | |||
---- | |||
@Theme(MyTheme.THEME_NAME) | |||
@Component(service = UI.class, property = { | |||
"com.liferay.portlet.display-category=category.vaadin", | |||
"javax.portlet.name=my.vaadin.app.app.1.0.0", | |||
"javax.portlet.display-name=Tutorial Portlet", | |||
"javax.portlet.security-role-ref=power-user,user", | |||
"com.vaadin.osgi.liferay.portlet-ui=true"}) | |||
public class MyUI extends UI { | |||
... | |||
} | |||
---- |
@@ -7,11 +7,11 @@ | |||
include::portal-overview.asciidoc[leveloffset=+2] | |||
include::portal-eclipse.asciidoc[leveloffset=+2] | |||
include::portal-ui.asciidoc[leveloffset=+2] | |||
include::portal-liferay.asciidoc[leveloffset=+2] | |||
include::portal-osgi.asciidoc[leveloffset=+2] | |||
include::portal-ui.asciidoc[leveloffset=+2] | |||
include::portal-liferay.asciidoc[leveloffset=+2] | |||
include::portal-deployment.asciidoc[leveloffset=+2] | |||
@@ -7,6 +7,10 @@ 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 | |||
@@ -33,9 +37,6 @@ changes to the UI itself, but only the following: | |||
* 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. |
@@ -1,100 +0,0 @@ | |||
--- | |||
title: Creating a Generic Portlet in Eclipse | |||
order: 2 | |||
layout: page | |||
--- | |||
[[portal.eclipse]] | |||
= Creating a Generic Portlet in Eclipse | |||
*_This section has not yet been updated for Vaadin Framework 8._* | |||
Here we describe the creation of a generic portlet project in Eclipse. You can | |||
use the Maven archetypes also in other IDEs or without an IDE. | |||
For Liferay portlet development, you may instead want to use the Maven archetype | |||
or Liferay IDE to create the project, as described in | |||
<<dummy/../../../framework/portal/portal-liferay#portal.liferay,"Developing | |||
Vaadin Portlets for Liferay">>. | |||
[[portal.eclipse.vaadin]] | |||
== Creating a Project with Vaadin Plugin | |||
The Vaadin Plugin for Eclipse has a wizard for easy creation of generic portlet | |||
projects. It creates a UI class and all the necessary descriptor files. | |||
Creating a portlet project is almost identical to the creation of a regular | |||
Vaadin servlet application project. For a full treatment of the New Project | |||
Wizard and the possible options, please see | |||
<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.creation,"Creating | |||
the Project">>. | |||
. Start creating a new project by selecting from the menu "File > New > Project..."+ | |||
//TODO Use ellipsis | |||
//<?dbfo-need height="8cm" ?> | |||
. In the [guilabel]#New Project# window that opens, select "Web > Vaadin 7 Project" and click [guibutton]#Next#. | |||
//<?dbfo-need height="10cm" ?> | |||
. In the [guilabel]#Vaadin Project# step, you need to set the basic web project | |||
settings. You need to give at least the project name, the runtime, select | |||
[guilabel]#Generic Portlet# for the [guilabel]#Deployment configuration#; the | |||
default values should be good for the other settings. | |||
ifdef::web[] | |||
+ | |||
image::img/project-new-portlet-1.png[] | |||
endif::web[] | |||
+ | |||
You can click [guibutton]#Finish# here to use the defaults for the rest of the | |||
settings, or click [guibutton]#Next#. | |||
. The settings in the [guilabel]#Web Module# step define the basic servlet-related | |||
settings and the structure of the web application project. All the settings are | |||
pre-filled, and you should normally accept them as they are and click | |||
[guibutton]#Next#. | |||
. The [guilabel]#Vaadin project# step page has various Vaadin-specific application | |||
settings. These are largely the same as for regular applications. Setting them | |||
here is easiest - later some of the changes require changes in several different | |||
files. The [guilabel]#Create portlet template# option should be automatically | |||
selected. You can give another portlet title of you want. You can change most of | |||
the settings afterward. | |||
+ | |||
image::img/project-new-portlet-3.png[] | |||
[guilabel]#Create project template#:: Creates a UI class and all the needed portlet deployment descriptors. | |||
[guilabel]#Application name#:: The application name is used in the title of the browser window, which is | |||
usually invisible in portlets, and as an identifier, either as is or with a | |||
suffix, in various deployment descriptors. | |||
[guilabel]#Base package name#:: Java package for the UI class. | |||
[guilabel]#Application class name#:: Name of the UI class. The default is derived from the project name. | |||
[guilabel]#Theme name#:: Name of the custom portlet theme to use. | |||
[guilabel]#Portlet version#:: Same as in the project settings. | |||
[guilabel]#Portlet title#:: The portlet title, defined in [filename]#portlet.xml#, can be used as the | |||
display name of the portlet (at least in Liferay). The default value is the | |||
project name. The title is also used as a short description in | |||
[filename]#liferay-plugin-package.properties#. | |||
[guilabel]#Vaadin version#:: Same as in the project settings. | |||
+ | |||
Finally, click [guibutton]#Finish# to create the project. | |||
. Eclipse may ask you to switch to J2EE perspective. A Dynamic Web Project uses an | |||
external web server and the J2EE perspective provides tools to control the | |||
server and manage application deployment. Click [guibutton]#Yes#. | |||
@@ -1,34 +1,35 @@ | |||
--- | |||
title: Developing Vaadin Portlets for Liferay | |||
order: 3 | |||
order: 4 | |||
layout: page | |||
--- | |||
[[portal.liferay]] | |||
= Developing Vaadin Portlets for Liferay | |||
*_This section has not yet been updated for Vaadin Framework 8._* | |||
A Vaadin portlet requires resources such as the server-side Vaadin libraries, a | |||
theme, and a widget set. You have two basic ways to deploy these: either | |||
globally in Liferay, so that the resources are shared between all Vaadin | |||
portlets, or as self-contained WARs, where each portlet carries their own | |||
resources. | |||
The self-contained way is easier and more flexible to start with, as the | |||
different portlets may have different versions of the resources. Currently, the | |||
latest Maven archetypes support the self-contained portlets, while with portlets | |||
created with the Vaadin Plugin for Eclipse only support globally deployed | |||
resources. | |||
Using shared resources is more efficient when you have multiple Vaadin portlets | |||
on the same page, as they can share the common resources. However, they must use | |||
exactly same Vaadin version. This is recommended for production environments, | |||
where you can even serve the theme and widget set from a front-end server. You | |||
can install the shared resources as described in <<portal.liferay.install>>. | |||
theme, and a widget set. You have three basic ways to deploy these: either | |||
globally in Liferay so that the resources are shared between all Vaadin | |||
portlets, as self-contained WARs where each portlet carries their own | |||
resources or as OSGi bundles in Liferay 7. | |||
For Liferay 7 and OSGi portlets, see <<dummy/../../../framework/portal/portal-osgi#portal.osgi,"OSGi Portlets on Liferay 7">>. This is the recommended approach when using Vaadin 8.1 or later and Liferay 7. | |||
Currently, the latest Maven archetype supports the OSGi approach. | |||
The material below applies mostly to non-OSGi portlets. | |||
== Developing Vaadin Portlets for Liferay 6.2 | |||
In non-OSGi environments, the self-contained approach to static resources is | |||
easier and more flexible, as the different portlets may have different | |||
versions of the resources. | |||
Using shared resources is not recommended as it forces all portlets on a page | |||
to use the same Vaadin version and resources. If using this approach, you can | |||
install the shared resources as described in <<portal.liferay.install>>. | |||
At the time of writing, the latest Liferay release 6.2 is bundled with a version | |||
of Vaadin release 6. If you want to use Vaadin 7 portlets with shared resources, | |||
of Vaadin release 6. If you want to use Vaadin 8 portlets with shared resources, | |||
you first need to remove the old ones as described in <<portal.liferay.remove>>. | |||
[[portal.liferay.profile]] | |||
@@ -118,6 +119,10 @@ Creation of Vaadin a Maven project is described in | |||
Vaadin with Maven">>. For a Liferay project, you should use the | |||
[literal]#++vaadin-archetype-liferay-portlet++#. | |||
Note: For creating Liferay 6.2 projects for Vaadin Framework 8.1, use the 8.0 | |||
version of the archetype and then update the dependency versions for Vaadin | |||
Framework. | |||
[[portal.liferay.project.archetype-parameters]] | |||
=== Archetype Parameters | |||
@@ -164,9 +169,8 @@ long as you have a single portlet, but causes a problem if you have multiple | |||
portlets. To solve this, Vaadin portlets need to use a globally installed widget | |||
set, theme, and Vaadin libraries. | |||
__Liferay 6.2, which is the latest Liferay version at the time of publication of | |||
this book, comes bundled with an older Vaadin 6 version. If you want to use | |||
Vaadin 7, you need to remove the bundled version and install the newer one | |||
__Liferay 6.2 comes bundled with an older Vaadin 6 version. If you want to use | |||
Vaadin 8, you need to remove the bundled version and install the newer one | |||
manually as described in this chapter.__ | |||
In these instructions, we assume that you use Liferay bundled with Apache | |||
@@ -218,19 +222,19 @@ copy their contents to [filename]#tomcat-x.x.x/webapps/ROOT/html/VAADIN#. | |||
+ | |||
[subs="normal"] | |||
---- | |||
[prompt]#$# [command]#unzip# path-to/vaadin-server-7.1.0.jar 'VAADIN/*' | |||
[prompt]#$# [command]#unzip# path-to/vaadin-server-8.1.0.jar 'VAADIN/*' | |||
---- | |||
+ | |||
[subs="normal"] | |||
---- | |||
[prompt]#$# [command]#unzip# path-to/vaadin-themes-7.1.0.jar 'VAADIN/*' | |||
[prompt]#$# [command]#unzip# path-to/vaadin-themes-8.1.0.jar 'VAADIN/*' | |||
---- | |||
+ | |||
[subs="normal"] | |||
---- | |||
[prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-7.1.0.jar 'VAADIN/*' | |||
[prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-8.1.0.jar 'VAADIN/*' | |||
---- | |||
@@ -252,7 +256,7 @@ vaadin.widgetset=com.vaadin.server.DefaultWidgetSet | |||
# Theme to use | |||
# This is the default theme if nothing is specified | |||
vaadin.theme=reindeer | |||
vaadin.theme=valo | |||
---- | |||
The allowed parameters are: | |||
@@ -266,7 +270,7 @@ application server; in Liferay with Tomcat it would be located at | |||
notation. If the parameter is not given, the default widget set is used. | |||
[parameter]#vaadin.theme#:: Name of the theme to use. If the parameter is not given, the default theme is | |||
used, which is [literal]#++reindeer++#. | |||
used, which is [literal]#++valo++#. | |||
@@ -0,0 +1,63 @@ | |||
--- | |||
title: Portlet UI | |||
order: 3 | |||
layout: page | |||
--- | |||
[[portal.osgi]] | |||
= OSGi Portlets on Liferay 7 | |||
IMPORTANT: The OSGi support as described above is currently being developed and only available in the Framework 8.1 prerelease versions, starting from 8.1.0.beta1. | |||
Lifeary 7 supports modular portlet development using OSGi, and enables e.g. | |||
using multiple different Vaadin versions in different portlets on a page. | |||
For general OSGi considerations with Vaadin Framework such as packaging and | |||
bundle manifests, and how to publish static resources such as themes and | |||
widget sets, see | |||
<<dummy/../../../framework/advanced/advanced-osgi#advanced.osgi,"Vaadin OSGi Support">>. | |||
[[portal.osgi.portlet]] | |||
== Publishing a Portlet With OSGi | |||
Publishing an OSGi portlet on Liferay 7+ can be done in two ways: using | |||
annotations or using properties. | |||
Annotating a UI class with [interfacename]#@VaadinLiferayPortletConfiguration# | |||
(available in `vaadin-liferay-integration`) and making it an OSGi service of type | |||
[classname]#UI# is the easiest way to automatically publish the UI as a portlet | |||
and configure it to use the correct static resources. | |||
[source, java] | |||
---- | |||
@Theme(MyTheme.THEME_NAME) | |||
@VaadinLiferayPortletConfiguration(name = "Vaadin.Tutorial.1", displayName = "Vaadin Tutorial App") | |||
@Component(service = UI.class) | |||
public class MyUI extends UI { | |||
... | |||
} | |||
---- | |||
When using this approach, it is not necessary to create all the portlet | |||
property files that plain JSR-362 portlets require. | |||
Alternatively, the property [literal]#com.vaadin.osgi.liferay.portlet-ui=true# | |||
can be used when publishing a UI as an OSGi service to publish the UI as a portlet. | |||
[source, java] | |||
---- | |||
@Theme(MyTheme.THEME_NAME) | |||
@Component(service = UI.class, property = { | |||
"com.liferay.portlet.display-category=category.vaadin", | |||
"javax.portlet.name=my.vaadin.app.app.1.0.0", | |||
"javax.portlet.display-name=Tutorial Portlet", | |||
"javax.portlet.security-role-ref=power-user,user", | |||
"com.vaadin.osgi.liferay.portlet-ui=true"}) | |||
public class MyUI extends UI { | |||
... | |||
} | |||
---- | |||
An OSGi portlet should be packaged as a JAR with a proper OSGi bundle | |||
manifest, and deployed to a portal that has its required bundles installed. |
@@ -7,12 +7,14 @@ layout: page | |||
[[portal.overview]] | |||
= Overview | |||
Vaadin supports running UIs as portlets in a portal, as defined in the JSR-286 | |||
(Java Portlet API 2.0) standard. A portlet UI is defined just as a regular UI, | |||
but deploying to a portal is somewhat different from deployment of regular web | |||
applications, requiring special portlet descriptors, etc. Creating the portlet | |||
project with the Vaadin Plugin for Eclipse or a Maven archetype automatically | |||
generates the necessary descriptors. | |||
Vaadin Framework supports running UIs as portlets in a portal, as defined in | |||
the JSR-286 (Java Portlet API 2.0) standard. A portlet UI is defined just as a | |||
regular UI, but deploying to a portal is somewhat different from deployment of | |||
regular web applications, requiring special portlet descriptors, etc. Creating | |||
the portlet project with the Maven archetype automatically generates the | |||
necessary descriptors. | |||
Vaadin Framework also supports developing OSGi portlets for Liferay 7. | |||
In addition to providing user interface through the Vaadin UI, portlets can | |||
integrate with the portal to switch between portlet modes and process special | |||
@@ -23,5 +25,3 @@ Vaadin especially supports the Liferay portal and the needed portal-specific | |||
configuration in this chapter is given for Liferay. Vaadin also has a special | |||
Liferay IPC add-on to enable communication between portlets. | |||
@@ -1,6 +1,6 @@ | |||
--- | |||
title: Portlet UI | |||
order: 4 | |||
order: 2 | |||
layout: page | |||
--- | |||
@@ -32,34 +32,19 @@ public class MyportletUI extends UI { | |||
} | |||
---- | |||
If you created the project as a Servlet 3.0 project, the generated UI stub | |||
includes a static servlet class annotated with [classname]#@WebServlet#, as | |||
described in | |||
<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.exploring,"Exploring | |||
the Project">>. | |||
---- | |||
@WebServlet(value = "/*", asyncSupported = true) | |||
@VaadinServletConfiguration(productionMode = false, | |||
ui = MyportletUI.class) | |||
public static class Servlet extends VaadinServlet { | |||
} | |||
---- | |||
This enables running the portlet UI in a servlet container while developing it, | |||
which may be easier than deploying to a portal. For Servlet 2.4 projects, a | |||
[filename]#web.xml# is created. | |||
For OSGi portlets in Liferay 7, use additional annotations as described in | |||
<<dummy/../../../framework/portal/portal-osgi#portal.osgi,"OSGi Portlets on Liferay 7">>. | |||
The portlet theme is defined with the [classname]#@Theme# annotation as usual. | |||
The theme for the UI must match a theme installed in the portal. You can use any | |||
of the built-in themes in Vaadin. If you use a custom theme, you need to | |||
compile it to CSS with the theme compiler and install it in the portal under the | |||
[filename]#VAADIN/themes# context to be served statically. | |||
[filename]#VAADIN/themes# context to be served statically, or use the OSGi | |||
portlet mechanisms to publish the theme. | |||
In addition to the UI class, you need the portlet descriptor files, Vaadin | |||
libraries, and other files as described later. | |||
<<figure.portal.helloworld.project>> shows the complete project structure under | |||
<<figure.portal.helloworld.project>> shows a complete project structure under | |||
Eclipse. | |||
[[figure.portal.helloworld.project]] | |||
@@ -73,5 +58,27 @@ application will show as illustrated in <<figure.portal.helloworld>>. | |||
.Hello World Portlet | |||
image::img/liferay-helloworld.png[] | |||
[[portal.ui.servlet]] | |||
== Testing Portlet UIs as Servlets | |||
If a portlet does not use any specific portlet APIs, deploying it as a servlet | |||
can make testing it easier than deploying it to a portal. | |||
If you created the project as a Servlet 3.0 project, the generated UI stub | |||
includes a static servlet class annotated with [classname]#@WebServlet#, as | |||
described in | |||
<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.exploring,"Exploring | |||
the Project">>. | |||
Otherwise, the following snippet can be used. | |||
---- | |||
@WebServlet(value = "/*", asyncSupported = true) | |||
@VaadinServletConfiguration(productionMode = false, | |||
ui = MyportletUI.class) | |||
public static class Servlet extends VaadinServlet { | |||
} | |||
---- | |||