How to create and use a custom Magnolia Maven module for custom Java

components :keywords: _ui-framework-naming, how-to-guide

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

Parameter	Example value	Explanation
Maven `groupId`	`info.magnolia.documentation`	Typically reflects the name or domain of your company or projects
Maven `artifactId`	`my-ui-components`	Project-specific identifier
Maven artifact `version`	`1.0-SNAPSHOT`	Project version: when creating a new project, use the value suggested (`1.0-SNAPSHOT`).
package	`info.magnolia.documentation.newui`	Package name for Java classes reflecting both your company (or domain) and the specific project
magnolia-bundle-version	`6.2`	The Magnolia version from which your custom project inherits
Module class name	`MyUiModule`	The java class name of the autogenerated module class
project-name	`my-ui-components`	Project name

Maven groupId

info.magnolia.documentation

Typically reflects the name or domain of your company or projects

Maven artifactId

my-ui-components

Project-specific identifier

Maven artifact version

1.0-SNAPSHOT

Project version: when creating a new project, use the value suggested (1.0-SNAPSHOT).

package

info.magnolia.documentation.newui

Package name for Java classes reflecting both your company (or domain) and the specific project

magnolia-bundle-version

6.2

The Magnolia version from which your custom project inherits

Module class name

MyUiModule

The java class name of the autogenerated module class

project-name

my-ui-components

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 the java folder, the archetype has created folders to reflect the Java package info.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:

my-ui-components/pom.xml

<?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:

Compile-time dependencies in the POM file
Runtime dependencies in the Magnolia module descriptor

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

groupId	artifactId	Module name	Notes
`info.magnolia`	`magnolia-core`	`core`	Magnolia main core module.
`info.magnolia.ui`	`magnolia-ui-framework`	`ui-framework-core`	Magnolia UI core framework for building UIs.

info.magnolia

magnolia-core

core

Magnolia main core module.

info.magnolia.ui

magnolia-ui-framework

ui-framework-core

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.

my-ui-components/pom.xml (fragment)

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

src/main/resources/META-INF/magnolia/my-ui-components.xml (generated version)

<?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:

src/main/resources/META-INF/magnolia/my-ui-components.xml

<?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 https://bitbucket.org/magnolia-cms/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.

Parent POM (fragment)

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

Webapp POM (fragment)

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

How to create and use a custom Magnolia Maven module for custom Java

Creating a custom Magnolia Maven module

Running the archetype command

Required Maven archetype parameters

Generated files and folders

Overview

Details of src/main

The POM file

Defining module dependencies

Module identifiers

Compile-time dependencies in the POM file

Runtime dependencies in the module descriptor

Result

Git

Using the custom module on your Magnolia instance

Adding the custom module to a custom webapp via Maven

Location

Main doc sections

Details of `src/main`