Magnolia 6.1 reached end of life on March 31, 2021. This branch is no longer supported, see End-of-life policy.
A Magnolia module can be purely file based or it can be wrapped in a Maven project.
These two folder trees show typical folder structures rather than structures with all folders possible.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/
├── config.yaml
├── 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 in WEB-INF/config/default/magnolia.properties
and its default value is $magnolia.home/modules
. To see the current value of the property, go to the Config Info tab in the About Magnolia app. Set the magnolia.resources.filesystem.observation.excludedDirectories
property to exclude directories from being observed for changes. (See Configuration management - magnolia.resources.filesystem.observation.excludedDirectories.)
<module-name>
folder contains exactly the same content in a Maven module and folder-based module. In a Maven module this folder is within src/main/resources
. In a folder-based modules this folder is within $magnolia.resources.dir
.é
, à
, ç
, ä
, ö
, ü
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.
apps | optional Configuration data for apps (YAML files) |
decorations | optional Definition decorator files (YAML files), see Definition decoration. Contains subfolders. |
dialogs | optional Dialogs (YAML files), may contain subfolders. |
fieldTypes | optional Fieldtype definitions (YAML files) for the Magnolia 5 UI framework. |
i18n | optional i18n message bundle (.properties files). |
messageViews | optional MessageView definitions (YAML files). |
renderers | optional Renderer definitions. |
webresources | optional All the web resources, typically contains subfolders. (Folder name is arbitrary.) |
templates | optional Template definitions (YAML files) and scripts with subfolders. |
restEndpoints | optional REST endpoint definitions (YAML files), with subfolders. |
virtualURIMappings | optional Virtual URI mapping definitions (YAML files) to redirect incoming requests to the actual content locations. |
A definition item is a component configuration for executing tasks in a Magnolia instance. Template definitions, dialog definitions, app definitions (also known as app descriptors), renderer definitions, themes definitions, field definitions and REST endpoint definitions are all examples of such definition items. The majority of these items can be configured via YAML, in which case they are registered in a specific registry. The items registered can be seen in the Definitions app. Even though definition items can be configured via JCR in the The following folders host the definition items: configuration
workspace, configuring them in YAML files is the recommended approach.apps
, commands
, dialogs
, fieldTypes
, messageViews
, renderers
, templates
, traits
, virtualURIMappings
. For more information see Module definition items.
Module descriptor is a Magnolia-specific file that identifies and defines a module. When you start Magnolia, the system identifies available modules by locating each module's descriptor file. Magnolia Maven-based modules must provide a module descriptor. It is located at In a Magnolia file-based module (light module), the descriptor is located at For Magnolia light modules, module descriptors currently support module dependencies only.In Magnolia Maven modules
src/main/resources/META-INF/magnolia/<module-name>.xml
. See XML-based module descriptor.In light modules
$magnolia.resources.dir/example-light-module/module.yaml
. See YAML-based module descriptor.
A Magnolia Maven-based module may contain the src/main/resources/<module-name>/config.yaml
file. It contains configuration data, which is applied to the Java bean properties of the Magnolia module class. See Module configuration for more information.
As of 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
.
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.
If you are familiar with Java and Maven, you can use Maven to create and build your Magnolia module. Using Maven streamlines 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.
Magnolia provides a set of Maven archetypes for various tasks, one of which is creating a Magnolia Maven module.
Before running the Maven archetype
command, please read How to use Magnolia Maven archetypes: Check Maven settings.
If you are not familiar with the Maven archetype plugin, please get familiar with How to use Magnolia Maven archetypes: The archetype plugin.
Open a shell and change to the directory where you want the Magnolia Maven module skeleton to be created.
cd /Users/jdoe/repositories/magnolia
Run the following command:
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-module-archetype -DarchetypeVersion=RELEASE
Maven prompts you to specify values for several parameters. Use values that fit your requirements:
Parameter | Example value | Explanation |
---|---|---|
Maven groupId |
com.example
| Typically reflects the name or domain of your company or projects. |
Maven artifactId | foobar-module | Project-specific identifier. |
Maven artifact version | 1.0-SNAPSHOT | Project version. Typically, when creating a new project, use the value suggested by Maven, for example 1.0-SNAPSHOT . |
package |
com.example.modules.foobar
| Package name for Java classes reflecting both your company (or domain) and the specific project. |
magnolia-bundle-version | 6.1 | Magnolia version from which your custom project inherits. |
module-class-name | FoobarModule | The Java class name of the autogenerated module class. |
project-name | foobar-module | Project name. |
After you have finished entering the values, the archetype plugin displays their list and asks you to confirm it. If you confirm by pressing ENTER
, the plugin generates the skeleton of your archetype. You should see a BUILD SUCCESS
message at the end of the process. If you press N
or CTRL
+ C
, nothing is generated.
my-module/ ├── pom.xml └── src ├── main │ ├── java │ └── resources └── test ├── java └── resources
The
java
and resources
directories contain more subfolders. For further details, see above.