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.2.4 or higher (see Choosing an archetype version).
Running the archetype command
Open a shell and change to the directory where you want to create the new module.
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:
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:
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|
The Magnolia version from which your custom project inherits
|Module class name||The java class name of the autogenerated module class|
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
The tree below shows only three sub-levels (see details of
The archetype creates some directories that you will not need for the tasks you are about to do. You can delete these folders:
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):
- Lines 2–ff:
src/main/javais where to add Java source classes in a Maven module.
javafolder, the archetype has created folders to reflect the Java package
info.magnolia.documentation.newuias specified while running the archetype create command.
- Module class (
- Module version handler class (
- Module class (
- Line 13: XML-based module descriptor (
You will edit the file later to define module runtime dependencies and to register components.
- Line 18: i18n message bundle (
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:Be aware of the following:
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.
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).
|Maven artifact specification||Magnolia module name|
|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.
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
This is how the module descriptor has been generated by the archetype: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 later.
Your module descriptor file should now look like this:
The custom Magnolia Maven module that you have just created is the base for adding Java classes (e.g. for custom UI components).
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
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
Edit the webapp POM. Add a new
<dependency>entry to the