XML-based module descriptor

This page is about the XML-based module descriptor file which identifies and defines a Magnolia Maven module. If you are using a Magnolia light module, you should use a YAML-based module descriptor.

The XML file:

Conforms to module.dtd.
Is stored in src/main/resources/META-INF/magnolia/<module-name>.xml
Can refer to nodes of the module pom file.

When you start Magnolia, the system identifies available modules by locating each module’s descriptor file.

Benefits of a module descriptor

The XML-based module descriptor has a number of benefits:

Dependency injection: Inject components into the module.
Module version handling: Smoother version changes with Maven.
Dependencies: Define runtime and install time dependencies to other modules.
Servlets: Register servlets in your module.
Workspaces: Create workspaces.
Module class: Register a module class that allows you to define module specific properties.

Example module descriptor

Here is an example XML Maven module descriptor that defines a module class (class element), a module version handler (versionHandler element), an IoC component and a dependency on the ui-admincentral module.

Note how you can refer to Maven properties within the module descriptor.

acme-geotagging-module.xml

<!DOCTYPE module SYSTEM "module.dtd">
<module>
  <name>acme-geotagging-module</name>
  <displayName>Acme geotagging module.</displayName>
  <class>com.acme.GeotaggingModule</class>
  <versionHandler>com.acme.GeotaggingModuleVersionHandler</versionHandler>
  <version>${project.version}</version>
  <components>
    <id>app-geotagging</id>
  </components>
  <components>
    <id>app-geotagging-main</id>
    <component>
      <type>com.acme.geo.app.main.GeoTaggingMainSubappView</type>
      <implementation>com.acme.geo.app.main.GeoTaggingMainSubappViewImpl</implementation>
    </component>
  </components>
  <dependencies>
    <dependency>
      <name>ui-admincentral</name>
      <version>${project.version}</version>
    </dependency>
  </dependencies>
</module>

Module descriptor elements

Element Description

Element	Description
`name`	required Functional name of the module in the `config` workspace.
`version`	required Module version.
`class`	optional Name of the module class.
`description`	optional Full description of the module.
`displayName`	optional Display name of the module.
`versionHandler`	optional Name of the version handler class.
`properties`	optional Properties used with the version handler.
`dependencies`	optional Dependencies installed for the module.
`servlets`	optional Servlets included in the servlet filter.
`repositories`	optional Repositories used by the module.
`components`	optional Injected components used by the module.

name

required

Functional name of the module in the config workspace.

version

required

Module version.

class

optional

Name of the module class.

description

optional

Full description of the module.

displayName

optional

Display name of the module.

versionHandler

optional

Name of the version handler class.

properties

optional

Properties used with the version handler.

dependencies

optional

Dependencies installed for the module.

servlets

optional

Servlets included in the servlet filter.

repositories

optional

Repositories used by the module.

components

optional

Injected components used by the module.

Module naming

For each module you have to provide:

artifactId and groupId to the identify the Maven artifact
Name of the module descriptor file.
<name> of the module in the module descriptor file.

There are no strict naming conventions. You should give a name that reflects the purpose of the module. The name may also contain the name of your company.

Depending on the module purpose it might be a good idea to use the same value for the artifact ID and module name.

It is definitively good practice to name the module descriptor file by the pattern <module-name>.xml.

Example

Module name: Social Media Hub
Artifact ID: social-media-hub
Group ID: com.tinext.magnolia (contains the name of the creator Tinext.com)
Module descriptor file: social-media-hub.xml

Module versions

The syntax for a version is

from version / to version

where the version number consists of three parts: x.y.z. The x.y parts denote a major version and the z part a maintenance release. The y.z parts are optional. For a strict version dependency, use just one version string.

The info.magnolia.module.model.VersionRange class supports the following syntax to indicate version dependencies. Only three parts are supported: major, minor and security versions. The build number is not supported. See Runtime.Version for more information.

*: all versions.

In a YAML file, make sure to wrap * with quotes (version: "*").
1.2: version 1.2 only.
1.2/*: version 1.2 or higher.
1.2/1.2.9 or [1.2,1.2.9]: all versions between 1.2 and 1.2.9 (including 1.2 and 1.2.9).
[1.2,1.2.9[ or [1.2,1.2.9): all versions between 1.2 and 1.2.9 (including 1.2 but excluding 1.2.9).

Example Description

Example	Description
`3`	Major version 3.
`3.6`	Major version 3.6.
`3.6.3`	Major version 3.6 and maintenance version 3.
`3/*`	Major version 3 or higher.
`3.6/*`	Major version 3.6 or higher.
`3.6.3/*`	Major version 3.6 and maintenance version 3 or higher.
`*/3`	Major version 3 or earlier.
`*/3.6`	Major version 3.6 or earlier.
`*/3.6.3`	Major version 3.6 and maintenance version 3 or earlier.
`3.5/3.6.2` or `[3.5/3.6.2]`	All versions between 3.5 and 3.6.2 (including 3.5 and 3.6.2).
`[3.5/3.6.2[` or `[3.5/3.6.2)`	All versions between 3.5 and 3.6.2 (including 3.5 but excluding 3.6.2).

3

Major version 3.

3.6

Major version 3.6.

3.6.3

Major version 3.6 and maintenance version 3.

3/*

Major version 3 or higher.

3.6/*

Major version 3.6 or higher.

3.6.3/*

Major version 3.6 and maintenance version 3 or higher.

*/3

Major version 3 or earlier.

*/3.6

Major version 3.6 or earlier.

*/3.6.3

Major version 3.6 and maintenance version 3 or earlier.

3.5/3.6.2 or [3.5/3.6.2]

All versions between 3.5 and 3.6.2 (including 3.5 and 3.6.2).

[3.5/3.6.2[ or [3.5/3.6.2)

All versions between 3.5 and 3.6.2 (including 3.5 but excluding 3.6.2).

Module dependencies

You can define runtime or install time dependencies (not build dependencies). If you define a dependency on a module, then this module will be installed and started before your module. A dependency can be optional. Optional in this context means that if an optional module is not present, installation will proceed, but if the optional module is present, this module will be installed first. The dependencies could look like this:

<dependencies>
   <dependency>
      <name>core</name>
      <version>3.6.0/*</version>
   </dependency>
   <!-- in case cache module is present,
   make sure we install after so we can add a bypass -->
   <dependency>
      <name>cache</name>
      <version>3.6.0/*</version>
      <optional>true</optional>
   </dependency>
</dependencies>

Module dependencies define module loading order

The module dependencies define the order in which modules are loaded during startup. For example, if module-a depends on module-b, module-b will be loaded before module-a. The order becomes important, for example, if both module-a and module-b decorate the same definition or if module-a inherits a definition from module-b.

Decorations are applied in the module load order.

Workspaces

Workspaces can be defined in the module descriptor. If necessary Magnolia initializes these workspaces before the installation starts. As an example look at the data module:

  <repositories>
    <repository>
      <name>magnolia</name>
      <workspaces>
        <workspace>data</workspace>
      </workspaces>
      <nodeTypeFile>/mgnl-nodetypes/magnolia-module-data-nodetypes.xml</nodeTypeFile>
    </repository>
  </repositories>

Under the hood, these repository workspaces are registered and initialized by info.magnolia.module.delta.SetupModuleRepositoriesTask when the module is installed.

If you are using the Magnolia Content Types module, you can define workspaces (and node types) also in light modules.

Please read the page Defining JCR node types and workspaces, which provides an overview of all ways to define custom JCR node types and create new workspaces with Magnolia.

Feedback

DX Core

XML-based module descriptor

Benefits of a module descriptor

Example module descriptor

Module descriptor elements

Module naming

Module versions

Module dependencies

Module dependencies define module loading order

Workspaces

Location

Main doc sections