Magnolia 6.1 reached extended end of life on June 2, 2020. Support for this branch is limited, see End-of-life policy.
This tutorial explains how you can create custom Magnolia webapps with Maven. Using Maven allows you to customize your webapps with the POM files, which can be tracked with a version control system like Git. A tailored webapp makes building and deploying faster and has a positive impact on the performance of your instances. With Maven, you can streamline your Magnolia project to meet the specific demands of the project.
If you just want to try out Magnolia, follow instead the tutorial called How to get and adapt a bundle with Magnolia CLI.
A Java Web Application (webapp) is a collection of servlets, other Java classes, static resources such as HTML pages, other resources, and meta information that describes the webapp bundled together. You can run a webapp on a servlet container. A Java webapp has a typical structure. It can be packaged as a WAR file. A webapp usually contains already packed portions called libraries or modules as JAR files.
Magnolia provides several preconfigured webapps and bundles. Some of them are ideal candidates as a starting point to build your custom webapp.
We assume that you are familiar with Maven and the basics of POM files. Your Maven settings should comply with the Magnolia Maven setup, which provides access to the Magnolia Nexus repositories, and thus ensures that you can build the webapps described in the examples. If you are new to Magnolia, we recommend that you first carefully follow the Maven setup page.
When creating a custom webapp, you have to decide whether your webapp will contain DX Core modules or only Community Edition modules. If you go for the DX Core, you need credentials to access the DX Core repositories on Nexus and you also need a DX Core license to run the DX Core webapps. If you don't have these credentials yet, but want to try out the Magnolia DX Core, apply for a trial license.
This section describes two approaches to define a custom webapp with Maven. For both of them, keep in mind the following:
If your aim is a minimalistic webapp, we recommend using the magnolia-empty-webapp
as a base for your webapp project. it is also the base for every Magnolia webapp and provides the essentials such as the Core and UI modules. This approach is applied on the subpage Creating a minimal webapp with Maven. It could be suitable for you, if you aim at creating a custom headless instance.
Most of the preconfigured Magnolia webapps come with a feature-rich set allowing you to accomplish a number of different tasks and run complex websites. The most prominent preconfigured Magnolia webapps are these two:
magnolia-community-webapp
magnolia‑dx-core‑webapp
In the Creating a DX Core webapp with Maven part of this tutorial, the magnolia-dx-core-webapp
is used as a starting point. We then exclude some modules which are not necessary for the example use case.
When creating a feature-rich webapp, you cannot only exclude modules, you also need to add additional modules. Usually, it is common to do both, exclude and add modules.
Just as Maven provides archetypes to create a typical skeleton for Maven projects, Magnolia too provides an archetype to create a skeleton for a Magnolia Maven project. The Magnolia archetype comes with options for different tasks. Here, we use the magnolia-project-archetype
. It is an archetype that creates a Magnolia project with its parent POM and a webapp with its own POM.
Before running the maven
archetype
command, please read How to use Magnolia Maven archetypes: Check Maven settings.
If you are not familiar with the Maven archetype plugin, please also read How to use Magnolia Maven archetypes: The archetype plugin.
The first step to create your Maven-based custom webapp is running the archetype command. Change into the directory where you want to create the Maven project for the Magnolia webapp. In the directory, use a shell to run the following command:
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE
While the archetype script is running, Maven prompts you to supply values for a list of parameters. Some of them are Maven-specific, others concern only Magnolia. In some cases, Maven suggests a value. To accept it, enter RETURN
or specify your own value and press RETURN
.
Executing the archetype command is the very first step you always have to take irrespective of the webapp edition you wish to create (Community or DX Core) and the approach you want follow (minimal or feature-rich). The parameters you specify in the prompts have no influence on the edition type or the approach.
These are the parameters Maven prompts you with in the order they appear:
Paremeter | Example value | Explanation |
---|---|---|
groupId 1) | com.example | It typically reflects the name or domain of your company or projects. |
artifactId 1) | custom-project-minimal | Project-specific identifier. |
Maven artifact version | 1.0-SNAPSHOT | Project version. Typically, when creating a new project, use the value suggested, 1.0-SNAPSHOT . |
package | com.example | Package name for Java classes reflecting both your company (or domain) and the specific project.
|
magnolia-bundle-version |
| The Magnolia version from which your custom project inherits. If you are unsure, use the latest released version (see releases). This version is used in the |
project-name |
custom-project-minimal
| Project name. In many cases it is reasonable to use the same value as in |
1) See also the Maven Guide to naming conventions on groupId, artifactId, and version.
After entering a project-name
value, the archetype script lists all the values you have provided. Now you can:
Confirm your choice by pressing RETURN
. Maven will generate the skeleton based on your parameters.
CTRL
+C
. The script terminates, not creating anything. To start again, execute the archetype command as described above. If you have confirmed your choice of parameters, the script finishes the build with a BUILD SUCCESS
message.
Maven generates the following webapp skeleton:
custom-project-minimal/ ├── custom-project-minimal-webapp │ ├── pom.xml │ └── src └── pom.xml
src
directory, containing more subfolders. In Example 2, you add more resources to this directory.The POM files are the central pieces of the skeleton. Make sure you understand these files since you must adapt them in the examples to define the custom webapps.
The content of the parent POM file, generated for bundle version 6.1:
properties
and the dependencyManagement
sections may need some adjustments.The properties
section is where you define values such as versions. You can use the section in both the parent POM and the webapp POM.
For example, the archetype adds the
magnoliaBundleVersion
property.
In the dependencyManagement
section, you define the artifact dependencies that you also add to the module in the webapp POM.
In the skeleton, Option A and Option B were created, the latter as a comment.
Also, use the dependencyManagement
section to define the versions of other modules which you want to add to the webapp.
The contents of the webapp POM file:
Finally, in the dependencies
section of the webapp POM, you assemble the modules which should be part of the webapp. Since you are using a preconfigured Magnolia webapp as the base, the Magnolia archetype creates and adds the following options to the webapp POM:
magnolia-empty-webapp
magnolia-community-webapp
magnolia-dx-core-webapp
Each of these options has a dependency to two artifact types – pom
and war
.
Besides adding an existing webapp, you typically also add other dependencies to single modules.
For examples of creating custom webapps with Maven, see the following pages: