Module structure

A Magnolia module can be purely file based or it can be wrapped in a Maven project.

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

  Set the property magnolia.resources.filesystem.observation.excludedDirectories  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 .

• 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-_].

Module 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

mgnl create-light-module one-pager-module

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 set of Maven archetypes for various tasks, one of which is creating a Magnolia Maven module. 

Executing the archetype plugin command

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:

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.

Generated skeleton

my-module/
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   └── resources
    └── test
        ├── java
        └── resources

 The java and resources directories contain more subfolders. For further details, see above.