mirrors
/
vaadin-framework
mirror of https://github.com/vaadin/framework.git
Watch 1
Star 0
Fork 0
Code Issues 0 Releases 329 Wiki Activity
Browse Source

Update portlet documentation for OSGi portlets

tags/8.1.0.alpha7
Henri Sara 7 years ago
parent
d0a64a8049
commit
1f070e124d
8 changed files with 138 additions and 197 deletions
Split View Show Diff Stats
  1. 0
    34
      documentation/advanced/advanced-osgi.asciidoc
  2. 3
    3
      documentation/portal/chapter-portal.asciidoc
  3. 4
    3
      documentation/portal/portal-deployment.asciidoc
  4. 0
    100
      documentation/portal/portal-eclipse.asciidoc
  5. 32
    28
      documentation/portal/portal-liferay.asciidoc
  6. 63
    0
      documentation/portal/portal-osgi.asciidoc
  7. 8
    8
      documentation/portal/portal-overview.asciidoc
  8. 28
    21
      documentation/portal/portal-ui.asciidoc

+ 0
- 34
documentation/advanced/advanced-osgi.asciidoc View File

@@ -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 {
...
}
----

+ 3
- 3
documentation/portal/chapter-portal.asciidoc View File

@@ -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]


+ 4
- 3
documentation/portal/portal-deployment.asciidoc View File

@@ -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.

+ 0
- 100
documentation/portal/portal-eclipse.asciidoc View File

@@ -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

//&lt;?dbfo-need height="8cm" ?&gt;
. In the [guilabel]#New Project# window that opens, select "Web > Vaadin 7 Project" and click [guibutton]#Next#.
//&lt;?dbfo-need height="10cm" ?&gt;
. 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#.






+ 32
- 28
documentation/portal/portal-liferay.asciidoc View File

@@ -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++#.




+ 63
- 0
documentation/portal/portal-osgi.asciidoc View File

@@ -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.

+ 8
- 8
documentation/portal/portal-overview.asciidoc View File

@@ -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.




+ 28
- 21
documentation/portal/portal-ui.asciidoc View File

@@ -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 {
}
----




Write Preview
Loading…
Cancel
Save