How to create and use a custom Magnolia Maven module for custom Java
This page explains how to create a custom Magnolia Maven module with custom Java code and how to add it to your Magnolia bundle.
We assume that you are familiar with Maven and Java.
You need Magnolia Maven settings. Please see Maven setup for details on how to get access to Magnolia resources.
Creating a custom Magnolia Maven module
In this section, you create a Magnolia Maven module with the help of the Maven archetype plugin and a Magnolia archetype.
If the concept of Maven archetypes is completely new to you, have a look at How to use Magnolia Maven archetypes.
Make sure to use the Magnolia archetype version 1.3 or higher (see also Choosing an archetype version).
Running the archetype command
Open a shell and change to the directory where you want to create the new module.
cd ~/dev/repo/magnolia/chms-zeugs
There are several ways and possible parameters when calling the Maven archetype command. For further details, refer to How to use Magnolia Maven archetypes. We assume you are using the command in the same way as shown here:
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-module-archetype -DarchetypeVersion=RELEASE
Required Maven archetype parameters
After calling the archetype plugin command, you enter the interactive mode. The plugin prompts you to provide input for some parameters. For the given example here, we use these parameter values:
Parameter | Example value | Explanation |
---|---|---|
Maven |
|
Typically reflects the name or domain of your company or projects |
Maven |
|
Project-specific identifier |
Maven artifact |
|
Project version: when
creating a new project, use the value suggested ( |
package |
|
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 |
Module class name |
|
The java class name of the autogenerated module class |
project-name |
|
Project name |
After you have provided all the data, the plugin lists all your input
and asks for confirmation. Press ENTER
to confirm and wait for the
plugin to generate the skeleton of your archetype. The command should
finish with a SUCCESS
message in the console.
Generated files and folders
Overview
The tree below shows only three sub-levels (see
details of src/main
).
my-ui-components/ ├── pom.xml └── src ├── main │ ├── java │ └── resources └── test ├── java └── resources
The archetype creates some directories that you will not need for the tasks you are about to do. You can delete these folders:
-
my-ui-components/src/main/resources/mgnl-bootstrap-samples/my-ui-components
-
my-ui-components/src/main/resources/my-ui-components/templates
-
my-ui-components/src/main/resources/my-ui-components/dialogs
-
my-ui-components/src/main/resources/my-ui-components/webresources
-
my-ui-components/src/test
Details of src/main
Here is a detailed tree of the files and folders that have been created
in src/main
within the module (note the few deleted folders above):
src/main
src/main/
├── java
│ └── info
│ └── magnolia
│ └── documentation
│ └── newui
│ ├── MyUiModule.java
│ └── setup
│ └── MyUiModuleVersionHandler.java
└── resources
├── META-INF
│ └── magnolia
│ └── my-ui-components.xml
├── mgnl-bootstrap
│ └── my-ui-components
└── my-ui-components
└── i18n
└── module-my-ui-components-messages_en.properties
Note the following:
-
Lines 2–ff:
src/main/
java
is where to add Java source classes in a Maven module.
In thejava
folder, the archetype has created folders to reflect the Java packageinfo.magnolia.documentation.newui
as specified while running the archetype create command.-
Module class (
info.magnolia.documentation.newui.MyUiModule
) -
Module version handler class (
info.magnolia.documentation.newui.setup.MyUiModuleVersionHandler
)
-
-
Line 13: XML-based module descriptor (
src/main/resources/META-INF/magnolia/my-ui-components.xml
)
You will edit the file later to define module runtime dependencies and to register components. -
Line 18: i18n message bundle (
src/main/resources/my-ui-components/i18n/module-my-ui-components-messages_en.properties
)
The POM file
POM stands for project object model. It is an XML representation of a Maven project held in a file named pom.xml (see https://maven.apache.org/pom.html). The file defines dependency management, dependencies, resources, repositories and the build.
Here is pom.xml as generated by the Maven archetype:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>info.magnolia.documentation</groupId>
<artifactId>my-ui-components</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>my-ui-components Magnolia Module</name>
<!--
<description>Please uncomment and fill in ...</description>
-->
<properties>
<magnoliaBundleVersion>6.0.1-SNAPSHOT</magnoliaBundleVersion>
<javaVersion>1.8</javaVersion>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>info.magnolia.bundle</groupId>
<artifactId>magnolia-bundle-parent</artifactId>
<version>${magnoliaBundleVersion}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-core</artifactId>
</dependency>
<!-- TEST -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>${javaVersion}</source>
<target>${javaVersion}</target>
</configuration>
</plugin>
</plugins>
<!-- default resources configuration which will filter the module descriptor -->
<resources>
<resource>
<directory>src/main/resources</directory>
<includes>
<include>**/*</include>
</includes>
</resource>
<resource>
<filtering>true</filtering>
<directory>src/main/resources</directory>
<includes>
<include>META-INF/magnolia/*</include>
</includes>
</resource>
</resources>
</build>
<repositories>
<repository>
<id>magnolia.public</id>
<url>https://nexus.magnolia-cms.com/repository/public</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<!-- IF YOU NEED MODULES FROM THE ENTERPRISE VERSION, UNCOMMENT THE FOLLOWING REPOSITORY -->
<!--
<repository>
<id>magnolia.enterprise.releases</id>
<url>https://nexus.magnolia-cms.com/repository/enterprise</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
-->
<repository>
<id>vaadin-addons</id>
<url>https://maven.vaadin.com/vaadin-addons</url>
</repository>
</repositories>
</project>
Be aware of the following:
The generated POM file imports dependency management from
info.magnolia.bundle:magnolia-bundle-parent
(see lines 17–27 in the generated POM file above). This provides Maven
version management for many Magnolia modules and third-party libraries
(see BOM for third-party
libraries).
Defining module dependencies
A Magnolia Maven module should describe:
When adding a Maven dependency of the Magnolia Maven module, it is good practice to add that dependency in the Magnolia module descriptor too. |
The Magnolia Maven archetype creates such dependencies for the Magnolia
core
module by default.
In the next sections, you will add—as an example—another dependency for the Magnolia UI core framework for building UIs. If you want to create a custom module with custom UI components, adding the UI core framework is a good idea. For other use cases, you may want to add other dependencies.
Module identifiers
The identifier(s) to specify a Maven module dependency in the POM file and a Magnolia module in the Magnolia module descriptor are not the same (but may be similar).
groupId | artifactId | Module name | Notes |
---|---|---|---|
|
|
|
Magnolia main core module. |
|
|
|
Magnolia UI core framework for building UIs. |
Compile-time dependencies in the POM file
Among other things, the modules that the POM file defines compile time dependencies to other Maven modules.
Now add the dependency for the magnolia UI framework (core) module.
<dependencies>
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-core</artifactId>
</dependency>
<dependency>
<groupId>info.magnolia.ui</groupId>
<artifactId>magnolia-ui-framework</artifactId>
</dependency>
</dependencies>
In the snippet above, the dependency for junit has also been removed. Generally, you should add test classes to your modules. In the context of this tutorial, anything related to tests is not covered to keep things simple.
Runtime dependencies in the module descriptor
The module descriptor is the file that
makes a module a Magnolia module. In a Maven module, this is an
XML-based
module descriptor that must be located in the directory
src/main/resources/META-INF/magnolia
.
This is how the module descriptor has been generated by the archetype:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "module.dtd" >
<module>
<name>my-ui-components</name>
<displayName>${project.name}</displayName>
<description>${project.description}</description>
<class>info.magnolia.documentation.newui.MyUiModule</class>
<versionHandler>info.magnolia.documentation.newui.setup.MyUiModuleVersionHandler</versionHandler>
<version>${project.version}</version>
<!-- For more information on module descriptor configuration options -->
<!-- https://docs.magnolia-cms.com/product-docs/6.2/Modules/Module-descriptor/XML-based-module-descriptor.html -->
<dependencies>
<dependency>
<name>core</name>
<version>*</version>
</dependency>
<!-- Add other dependencies here, e.g the mte (magnolia templating essentials).
<dependency>
<name>mte</name>
<version>0.7/*</version>
</dependency>
-->
</dependencies>
</module>
Now add the dependency for the magnolia UI framework (core) module.
For each module in the dependencies
section, we specify a version. For
the given example, use 6.0/*
. This means the module must be version
6.0 or higher.
Your module descriptor file should now look like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "module.dtd" >
<module>
<name>my-ui-components</name>
<displayName>${project.name}</displayName>
<description>${project.description}</description>
<class>info.magnolia.documentation.newui.MyUiModule</class>
<versionHandler>info.magnolia.documentation.newui.setup.MyUiModuleVersionHandler</versionHandler>
<version>${project.version}</version>
<dependencies>
<dependency>
<name>core</name>
<version>6.0/*</version>
</dependency>
<dependency>
<name>ui-framework-core</name>
<version>6.0/*</version>
</dependency>
</dependencies>
</module>
Result
The custom Magnolia Maven module that you have just created is the base for adding Java classes (e.g. for custom UI components).
Git
You can get the source files for this custom Magnolia Maven module from our Git repository.
To get the same version of the module that you have created on this
page, you must check out the branch empty-custom-module
.
cd /User/jdoe/magnolia/custom-modules git clone ssh://git@git.magnolia-cms.com/documentation/my-ui-components.git cd my-ui-components/ git checkout empty-custom-module
Using the custom module on your Magnolia instance
To manage and maintain a custom Magnolia webapp, it is recommended you use Maven. If the topic is completely new to you, you may want to read Creating a custom webapp with Maven. |
Adding the custom module to a custom webapp via Maven
In this section, we assume that you have a custom Magnolia webapp that you manage with Maven. Add the new custom module like this:
-
Edit the the parent POM. Add a new
<dependency>
entry to<dependencies>
within the<dependencyManagement>
section.
<dependencyManagement>
<dependencies>
<!-- you may have
many more sections here -->
<!-- new entry for the new module -->
<dependency>
<groupId>info.magnolia.documentation</groupId>
<artifactId>my-ui-components</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
</dependencies>
</dependencyManagement>
-
Edit the webapp POM. Add a new
<dependency>
entry to the<dependencies>
section.
<dependencies>
<!-- you may have many more sections here -->
<!-- new entry for the new module -->
<dependency>
<groupId>info.magnolia.documentation</groupId>
<artifactId>my-ui-components</artifactId>
</dependency>
</dependencies>