Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Adding a Vaadin Portlet Module to an Existing Maven Multi-Module Project

Shows how to add a new Vaadin Portlet Module to an existing Vaadin or non-Vaadin multi-module project

This document describes how to add a new Vaadin Portlet module to a Maven multi-module project. The scenarios covered are 1) adding the Vaadin Portlet module to a Vaadin multi-module portlet project, where each portlet is packaged as a separate WAR file with a shared static asset WAR, and 2) adding the Vaadin portlet module to a non-Vaadin multi-module project, where the portlet module builds two WARs (one for the portlet and one for the static assets).

1. Adding a New Vaadin Portlet Module to an Existing Vaadin Multi-Module Portlet Project

Prerequisites

This short guide is applicable when:

  • you have an existing Vaadin Portlet multi-module project containing a bundle module and one or more Vaadin Portlet modules, as described in Creating Multi-Module Portlet Project; and

  • you have a Vaadin Portlet module (either built from the beginning or based on base-starter-flow-portlet); and

  • your objective is to integrate the new Vaadin Portlet module into the target project, so that you can build and deploy all Vaadin Portlet modules as separate WARs together with a shared static asset WAR.

Make Your Vaadin Portlet Module a Submodule of the Target Project

This step is identical to adding any Maven project as a submodule of an existing multi-module project. First, copy your Vaadin Portlet module (here, myproject-newportlet) inside the parent module of the multi-module project (here, myproject). Hence, in this imaginary scenario, it ends up in myproject/myproject-newportlet. Then register myproject-newportlet as a submodule in myproject/pom.xml:

<modules>
    <!-- portlet modules, any order if no dependencies -->
    <module>myproject-oldportlet</module>
    <module>myproject-newportlet</module>

    <!-- static assets module, should always be after portlet modules -->
    <module>myproject-bundle</module>
</modules>
Note
 The portlet modules should be added before the static asset module (here myproject-bundle). The internal order of the portlet modules doesn’t matter (unless there are project-specific interdependencies).

Also, update the parent property in the portlet module’s pom.xml to refer to the target project:

<parent>
    <groupId>com.myorg</groupId>
    <artifactId>myproject</artifactId>
    <version>1.0-SNAPSHOT</version>
</parent>

Replace names and versions as applicable to your project.

Add the New Portlet as a Dependency of the Static Asset Module

In the pom.xml of your bundle module (here, myproject/myproject-bundle/pom.xml), add the new Portlet Module artifact under <dependencies> with the classifier classes:

<dependency>
    <groupId>com.myorg</groupId>
    <artifactId>myproject-newportlet</artifactId>
    <version>1.0-SNAPSHOT</version>
    <classifier>classes</classifier>
</dependency>

Replace <groupId>, <artifactId> and <version> contents as required.

Remove Unnecessary Configuration from Portlet Module (if Applicable)

If your new Vaadin Portlet module was based on base-starter-flow-portlet, it contains plugins and executions that are no longer needed when the module is part of a Vaadin multi-module portlet project.

First, remove the entire vaadin-maven-plugin section from pom.xml (artifactId may alternatively be flow-maven-plugin, depending on your configuration):

<plugin>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-maven-plugin</artifactId>
    <executions>
        <!-- ... -->
    </executions>
</plugin>

Next, under maven-war-plugin in pom.xml, remove the entire execution with id static-files:

<execution>
    <id>static-files</id>
    <goals>
        <goal>war</goal>
    </goals>
    <configuration>
        <warName>vaadin-portlet-static</warName>
        <!-- ... -->
    </configuration>
</execution>

Since the target project builds its own static asset module, these are no longer needed in the portlet module. Next, you need to check that the portlet module is configured for inclusion in a multi-module project.

Configure the Added Portlet Module for the Multi-Module Project

In the pom.xml of the added portlet module, enable <attachClasses>:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <attachClasses>true</attachClasses>
    </configuration>
</plugin>

Additionally, you must set the location from which the resources are served by the common bundle WAR. In the new portlet module, ensure that the file src/main/resources/META-INF/VAADIN/config/flow-build-info.json exists and has the following contents:

{
  "externalStatsUrl": "/myproject-bundle/VAADIN/config/stats.json"
}

For portlets running in Liferay 7, it would be:

{
  "externalStatsUrl": "/o/myproject-bundle/VAADIN/config/stats.json"
}

The first component of the path (here, myproject-bundle) must match the WAR name of the deployed static asset WAR.

Note
 As this is a relative URL, it targets 127.0.0.1:8080. This should use the correct known URL of the bundle. For instance, localhost on port 80 would be http://127.0.0.1/myproject-bundle/VAADIN/config/stats.json.

For more information on setting up a multi-module project and the packaging of static assets, see Creating Multi-Module Portlet Project.

Package and Deploy the WAR Files

Run the following Maven command in the parent project:

mvn package

After the Maven build, a WAR file is created in the target folder of each portlet module, as well as in the bundle module: myproject-bundle/target/myproject-bundle.war, myproject-oldportlet/target/myproject-oldportlet.war, …​, myproject-newportlet/target/myproject-newportlet.war. To deploy, copy these files to the deployment directory of your web server or portal (webapps directory in Tomcat/Pluto).

2. Adding a New Vaadin Portlet Module to a Non-Vaadin Multi-Module Project

Prerequisites

This short guide is applicable when:

  • you have an existing Maven multi-module project that isn’t a Vaadin Portlet multi-module project; and

  • you have a Vaadin Portlet module (either created from the beginning or based on the base-starter-flow-portlet); and

  • your objective is to integrate the Vaadin Portlet module into the target project, so that you can build a portlet WAR and a static asset WAR for the Vaadin Portlet module.

Add the New Portlet Module to the Parent pom.xml

To add the Vaadin Portlet as a submodule in the existing multi-module project, follow the instructions under Make Your Vaadin Portlet Module a Submodule of the Target Project in the previous section.

Ensure that the New Portlet Module Builds Bundle and Portlet WAR Files

Ensure that the Vaadin Portlet pom.xml contains the vaadin-maven-plugin and two executions in the maven-war-plugin for building both the static asset bundle WAR and the portlet WAR. If your portlet module is based on base-starter-flow-portlet, vaadin-maven-plugin is added and the executions already exist with the ids static-files and portlet-war, respectively. The <warName> of the static asset bundle must be exactly vaadin-portlet-static for the project to work out of the box. To use a custom bundle name, you must add a flow-build-info.json file containing the static asset URL, as explained in Configure the Added Portlet Module for the Multi-Module Project.

Package and Deploy the WAR Files

Run the following Maven command in the parent project:

mvn package

After the Maven build, two WAR files are created: myproject-bundle/target/vaadin-portlet-static.war and myproject-newportlet/target/myproject-newportlet.war. To deploy, copy both files to the deployment directory of your web server or portal (webapps directory in Tomcat/Pluto).

FD930C2A-F63F-4457-97FA-9BA785D433A8