There instructions cover the steps for adding a custom module to an existing website project.
Prerequisites
- A parent pom and webapp. See Setting up a Magnolia website project.
Create the module
When you have an existing Magnolia project (parent pom and webapp) you need to move inside the directory that contains your parent pom.
From the command line run:
mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public/
Choose the archetype:
- An archetype to create STK Theme modules
- An archetype to create a Magnolia project (a parent pom and a webapp)
- An archetype to create basic Magnolia modules
- An archetype to create a Magnolia module to be hosted on the Magnolia Forge
- An archetype to create Magnolia modules using Blossom
Automates the creation of a Magnolia Cloud project: parent pom and webapp
An archetype to create a fresh Magnolia DX Core custom cloud bundle
Each archetype can have its own set of versions.
Choose info.magnolia.maven.archetypes:magnolia-project-archetype version:
- 1.1.0
- 1.2.0
- 1.2.1
- 1.2.2
- 1.2.3
- 1.2.4
- 1.2.5
- 1.2.6-SNAPSHOT
- 1.3
- 1.4-SNAPSHOT
Define the project:
groupId | com.mycompany.templates |
|---|---|
artifactId | mycompany-module-templates |
version | 1.0-SNAPSHOT |
package | com.mycompany.templates (press enter key to accept) |
magnolia-bundle-version | 6.2.10 The magnolia-bundle-version is a version of a collection of modules. This can be different than core module version. |
module-class-name | MyCompanyTemplatesModule |
module-name | mycompany-templates This name will show up in the configuration tree. Avoid using the word "module" here because it's redundant. |
Confirm success:
Confirm properties configuration: groupId: com.mycompany.templates artifactId: mycompany-module-templates version: 1.0-SNAPSHOT package: com.mycompany.templates magnolia-bundle-version: 6.2.10 module-class-name: MyCompanyTemplatesModule module-name: mycompany-templates Y: : Y [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: magnolia-module-archetype:1.4-SNAPSHOT [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.mycompany.templates [INFO] Parameter: artifactId, Value: mycompany-module-templates [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.mycompany.templates [INFO] Parameter: packageInPathFormat, Value: com/mycompany/templates [INFO] Parameter: module-class-name, Value: MyCompanyTemplatesModule [INFO] Parameter: magnolia-bundle-version, Value: 6.2.10 [INFO] Parameter: package, Value: com.mycompany.templates [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: groupId, Value: com.mycompany.templates [INFO] Parameter: module-name, Value: mycompany-templates [INFO] Parameter: artifactId, Value: mycompany-module-templates [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/META-INF/magnolia/mycompany-templates.xml [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/mycompany-templates/templates/components/dummy-component.ftl [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/mycompany-templates/templates/components/dummy-component.yaml [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/mycompany-templates/templates/pages/dummy-page.ftl [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/mycompany-templates/templates/pages/dummy-page.yaml [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/mycompany-templates/dialogs/pages/dummy-page-properties.yaml [WARNING] CP Don't override file /Users/rich.gange/mycompany-module-templates/src/main/resources/mycompany-templates/i18n/module-mycompany-templates-messages_en.properties [INFO] project created from Archetype in dir: /Users/rich.gange/Downloads/temp2/mycompany-module-templates [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 01:46 min [INFO] Finished at: 2021-07-06T14:35:40+02:00 [INFO] ------------------------------------------------------------------------
Create a dependency
In order for the module to be included in the war you need to add a dependency to the webapp pom.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.mycompany.webapps</groupId>
<artifactId>magnolia-cms</artifactId>
<version>6.2.10-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>magnolia-cms-webapp</artifactId>
<name>magnolia-cms: webapp</name>
<packaging>war</packaging>
<dependencies>
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-webapp</artifactId>
<type>pom</type>
</dependency>
<!-- Add the module dependency -->
<dependency>
<groupId>com.mycompany.templates</groupId>
<artifactId>mycompany-module-templates</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
</dependencies>
...
...
</project>
Tips
For every additional module added to the project you will find an entry in the parent pom.
<modules> <module>magnolia-cms-webapp</module> <module>mycompany-module-templates</module> </modules>
- There can be a discrepancy between bundle version and core module version.
Check the
info.magnolia.bundle.magnolia-bundle-parentpom for themagnoliaBundleVersion, which ultimately determines the version of core.<properties> <magnoliaBundleVersion>6.2.10</magnoliaBundleVersion> <javaVersion>1.8</javaVersion> </properties>
- Having a descriptor dependency on core is often not required.
Typically is can be set to *
/mycompany-module-templates/src/main/resources/META-INF/magnolia/mycompany-templates.xml<dependencies> <dependency> <name>core</name> <version>*</version> </dependency> <!-- Add other dependencies here, e.g the mte (magnolia templating essentials). <dependency> <name>mte</name> <version>0.7/*</version> </dependency> --> </dependencies>
- There is already a transitive dependency.
- The module does not make some configuration change to another module.
2 Comments
Charis Moutafidis
Important note, for this to work, I also had to add a dependency in the webapp's pom, something like this:
<dependency> <groupId>com.mycompany.templates</groupId> <artifactId>mycompany-module-templates</artifactId> <version>5.6-SNAPSHOT</version> </dependency>Video instruction reference: https://academy.magnolia-cms.com/display/MA/6.3.1+Empty+webapp
Richard Gange
Sorry for the super late notice. Good call. I will add that step today!