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.
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.
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 versionCopy
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
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>Copy
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.
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:
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.