Page tree
Skip to end of metadata
Go to start of metadata

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 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.
    (info) 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 within src/main/resources . In a folder-based modules this folder is within $magnolia.resources.dir.
  • Avoid spaces and special characters (ü, ä, ö) in <module-name>.

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.

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. 

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:

  1. Create a directory on your local file system where the project will be stored and change into this directory.
  2. 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/ 

  3. Choose an archetype when prompted. Here we choose the option magnolia-module-archetype which is a simple Magnolia project wrapped into Maven structure. Maven will then ask us for the standard Maven properties such as which version of Magnolia we will be using.

    Choose archetype:
    1: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-theme-archetype (An archetype to create STK Theme modules)
    2: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-project-archetype (An archetype to create a Magnolia project (a parent pom and a webapp))
    3: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-module-archetype (An archetype to create basic Magnolia modules)
    4: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-forge-module-archetype (An archetype to create a Magnolia module to be hosted on the Magnolia Forge)
    5: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-blossom-module-archetype (An archetype to create Magnolia modules using Blossom)
    Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 3
    Choose info.magnolia.maven.archetypes:magnolia-module-archetype version: 
    1: 1.1.0
    2: 1.2.0
    3: 1.2.1
    4: 1.2.2
    5: 1.2.3-SNAPSHOT
    Choose a number: 5:
    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-version': : 5.4
    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-version: 5.4
    module-class-name: MyModule
    module-name: myModule
     Y: : Y