Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
A Magnolia module can be purely file based or it can be wrapped in a Maven project.
Magnolia module wrapped in a typical Maven module structure before it is built. | File-based Magnolia module under $magnolia.resources.dir = Light module |
---|---|
<maven-module-name>/ ├── pom.xml └── src/ └── main/ ├── java/ └── resources/ ├── META-INF/ │ └── magnolia/ │ └── module-name.xml └── <module-name>/ ├── apps/ ├── dialogs/ │ └── myDialog.yaml ├── webresources/ └── templates/ ├── components/ │ ├── myComponent.ftl │ └── myComponent.yaml └── pages/ ├── myTemplate.ftl └── myTemplate.yaml | $magnolia.resources.dir/ └── <module-name>/ ├── apps/ ├── dialogs/ │ └── myDialog.yaml ├── module.yaml ├── webresources/ └── templates/ ├── components/ │ ├── myComponent.ftl │ └── myComponent.yaml └── pages/ ├── myTemplate.ftl └── myTemplate.yaml |
Notes:
magnolia.resources.dir
is a property defining the directory from which resources are loaded in a Magnolia instance. This directory is used for file-based resources such as light modules and for overriding classpath resources. The property is configured inWEB-INF/config/default/magnolia.properties
and has the default value$magnolia.home/modules
. To see the current value of the property, go to the Config Info tab in the About Magnolia app.
You can use symbolic links (a.k.a symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.
<module-name>
folder contains exactly the same content in a Maven module and folder-based module. In a Maven module this folder is withinsrc/main/resources
. In a folder-based modules this folder is within$magnolia.resources.dir
.- When creating a name for a module, do not use spaces, accented characters such as
é
,à
,ç
,ä
,ö
,ü
or special characters such as slashes/
,\
and so on. The name must match the regular expression[a-zA-Z0-9-_]
.
The create-light-module
command in the Magnolia CLI creates the module folder structure on the file system automatically.
Module subfolders
apps | optional Configuration data for apps (YAML files) |
decorations | optional Definition decorator files (YAML files) |
dialogs | optional Dialogs (YAML files), may have subfolders |
fieldTypes | optional FieldType definitions (YAML files). |
i18n | optional i18n message bundle (.properties files). |
messageViews | optional MessageView definitions (YAML files). |
webresources | optional All the web resources, typically contains subfolders. (Folder name is arbitrary.) |
templates | optional Template definitions (YAML files) and scripts with subfolders |
Folder-based module in $magnolia.resources.dir
Starting with Magnolia 5.4, a Magnolia module does not have to be a Maven module. You can add a file-based module in the $magnolia.resources.dir
directory.
By default $magnolia.resources.dir
is the webapp folder, for instance magnoliaAuthor
or magnoliaPublic
. See Add the module folder to $magnolia.home for more information about $magnolia.home
.
Creating a light module with Magnolia CLI
create-light-module
. Open a shell, cd
to your light modules directory, and execute the following command:mgnl create-light-module one-pager-module
é
, à
, ç
, ä
, ö
, ü
or special characters (e.g. slashes /
, \
and so on). The name must match the regular expression [a-zA-Z0-9-_]
.Note that this only works if you have installed Magnolia CLI, see Magnolia CLI Installation.
Magnolia Maven module
If you are familiar with Java and Maven you may want to use Maven to create and build your Magnolia module. Using Maven eases the process of creating a JAR file, deployment, and dependency management of your modules. All modules provided by Magnolia are built with Maven. This makes it easy to install or uninstall them by adding or removing a JAR file.
Creating a Magnolia Maven module with Maven archetypes
Magnolia provides a Maven archetype to build the skeleton of a Magnolia Maven module. The archetype provides options to build different modules:
- Basic Magnolia module
- Theme module
- Magnolia module to be hosted on the Magnolia Forge
- Magnolia module using Blossom
- Magnolia project (a parent pom and a webapp))
The archetypeCatalog is in
https://nexus.magnolia-cms.com/content/groups/public/
.
To choose an archetype:
- Create a directory on your local file system where the project will be stored and change into this directory.
Execute the following maven command:
mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public/
Choose an archetype when prompted. Here we choose the option
magnolia-module-archetype
which is a simple Magnolia project wrapped into Maven structure.Next, the script asks to choose the archetype version - we recommend to choose always the latest version.
Now you must prompt typical Maven properties such as groupId, artifactId, package name and version plus the Magnolia specific parameters magnolia-bundle-version, module-class-name and module-name.
When you have prompted all the parameters - the archetype summarizes your inputs and you must confirm or can skip.Define value for property 'groupId': : com.example Define value for property 'artifactId': : myModule Define value for property 'version': 1.0-SNAPSHOT: : Define value for property 'package': com.example: : Define value for property 'magnolia-bundle-version': : 5.6.6 Define value for property 'module-class-name': : MyModule Define value for property 'module-name': myModule: : Confirm properties configuration: groupId: com.example artifactId: myModule version: 1.0-SNAPSHOT package: com.example magnolia-bundle-version: 5.6.6 module-class-name: MyModule module-name: myModule Y: : Y
If you confirm, Maven generates the archetype skeleton.