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

There instructions cover the steps for adding a custom module to an existing website project. 

Prerequisites

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:

  1. An archetype to create STK Theme modules
  2. An archetype to create a Magnolia project (a parent pom and a webapp)
  3. An archetype to create basic Magnolia modules
  4. An archetype to create a Magnolia module to be hosted on the Magnolia Forge
  5. An archetype to create Magnolia modules using Blossom
  6. Automates the creation of a Magnolia Cloud project: parent pom and webapp

  7. 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.1.0
  2. 1.2.0
  3. 1.2.1
  4. 1.2.2
  5. 1.2.3
  6. 1.2.4
  7. 1.2.5
  8. 1.2.6-SNAPSHOT
  9. 1.3
  10. 1.4-SNAPSHOT

Define the project:

groupIdcom.mycompany.templates
artifactIdmycompany-module-templates
version

1.0-SNAPSHOT

packagecom.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-nameMyCompanyTemplatesModule
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.

/magnolia-cms/magnolia-cms-webapp/pom.xml
<?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-parent pom for the magnoliaBundleVersion, 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.
  • No labels

2 Comments

  1. Important note, for this to work, I also had to add a dependency in the webapp's pom, something like this:

    pom.xml
    <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

    1. Sorry for the super late notice. Good call. I will add that step today!