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

This page explains how to use Magnolia-specific Maven archetypes to jumpstart various Magnolia development tasks related to Magnolia Maven modules.

Archetype is a Maven project templating toolkit. An archetype is defined as an original pattern or model from which all other things of the same kind are made. ... Using archetypes provides a great way to enable developers quickly in a way consistent with best practices employed by your project or organization.

(Apache Maven ProjectIntroduction to Archetypes)

How to work with this page

Start by reading the Requirements section.

If you are not familiar with the Maven archetype plugin, go through the whole section describing it. At minimum, read our hints about choosing an archetype version

Finally, study the details about the Magnolia Maven archetypes.


Requirements

Maven

You need to install and set up Maven. Follow the procedure described on our Maven setup page. 

Check Maven settings

During the Maven setup, the settings.xml file is created for you as a CE user, a Forge user or a DX Core user.

Open the file and depending on which user type you are, check that it contains one of the following snippets. If not, add the snippet to the file. The snippet should be placed before the profiles section.

 For CE users
  <mirrors>
    <mirror>
      <id>magnolia.nexus.public</id>
      <url>https://nexus.magnolia-cms.com/content/groups/public</url>
      <mirrorOf>archetype</mirrorOf>
    </mirror>
  </mirrors>
 For forge users
  <mirrors>
    <mirror>
     <id>magnolia.nexus.public</id>
     <url>https://nexus.magnolia-cms.com/content/groups/public</url>
     <mirrorOf>archetype</mirrorOf>
    </mirror>
  </mirrors>
 For DX Core users
  <mirrors>
    <mirror>
      <id>magnolia.nexus.enterprise</id>
      <url>https://nexus.magnolia-cms.com/content/groups/enterprise/</url>
      <mirrorOf>archetype</mirrorOf>
      </mirror>
  </mirrors> 

The archetype plugin

(lightbulb) If you are already familiar with the Maven archetype plugin, read at least the subsection called Choosing an archetype version. Then, proceed to Magnolia Maven archetypes.

Maven provides the archetype:generate plugin with which you can create archetype-based project skeletons. For a complete list of all parameters that can be used with this plugin, please refer to the Apache reference page.

The plugin generates a skeleton of files and directories. Before executing the plugin command, change to the directory where you want to create the skeleton.

Here is the base command without any parameter:

mvn archetype:generate

To supply parameters to the command, you must use the -D$parameter-name=$parameter-value pattern, for example, -DarchetypeVersion=1.2.4.

A hint

To interrupt the archetype:generate command, press CTRL + C .

The interactive mode

When you execute mvn archetype:generate, with or without parameters, you enter the interactive mode, in which Maven prompts you for input.

The input may take form of a list of values to choose from, in which case you enter a number and press ENTER. Maven may also suggest a value to you such as 7 in the example below. To accept it, just hit ENTER.

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
6: 1.2.4
7: 1.2.5-SNAPSHOT
Choose a number: 7:

Sometimes, Maven prompts you to enter a literal value such as com.example and confirm with ENTER:

Define value for property 'groupId':

Choosing an archetype version

We highly recommend that you use the latest released archetype version or the SNAPSHOT version. (warning) Avoid using old versions.

If you call the plugin with the archetypeGroupId and archetypeArtifactId but without the archetypeVersion, the plugin automatically picks a version for you and it may be the oldest version.

Use the command in a form that lets you specify the archetype version. You can use -DarchetypeVersion=LATEST for the latest SNAPSHOT version or -DarchetypeVersion=RELEASE for the latest released version.

Currently, the latest released version is  1.2.5 .

Choosing an archetype

Using the archetype group ID, artifact ID and version

An archetype is uniquely defined by the following three parameters:

  • archetypeGroupId
  • archetypeArtifactId
  • archetypeVersion

When using these parameters with proper values, the plugin starts the interactive mode for the archetype you specify. Example:

mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE
List of available archetypes

If you omit both the archetypeGroupId and the archetypeArtifactId, the plugin collects a list of possible archetypes. Be aware that the list can be very long and it may take some time to generate it.

Depending on your internal Maven settings.xml, the list of available archetypes may be limited to the Magnolia archetypes only.

Choose an archetype by entering its number or apply a list filter.

Filtering in the interactive mode

When Maven presents a list of possible archetypes, you can apply a filter to it:

Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

To filter for Magnolia archetypes in this case, enter info.magnolia.maven.archetypes:magnolia. The list gets shorter and offers only the Magnolia archetypes.

Filtering with parameters

Alternatively, you can run the archetype:generate command with the filter property:

mvn archetype:generate -Dfilter=info.magnolia.maven.archetypes:magnolia

Confirming and finishing

In the last step, the plugin displays a list of values you entered 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.

 Click to see an example of the confirmation dialog.
Confirm properties configuration:
groupId: com.example
artifactId: fox-force-four
version: 1.0-SNAPSHOT
package: com.example.modules.foxforcefour
magnolia-bundle-version: 6.0
module-class-name: FoxforcefourModule
module-name: fox-force-four
 Y: :
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: magnolia-forge-module-archetype:1.2.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: fox-force-four
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.example.modules.foxforcefour
[INFO] Parameter: packageInPathFormat, Value: com/example/modules/foxforcefour
[INFO] Parameter: module-class-name, Value: FoxforcefourModule
[INFO] Parameter: magnolia-bundle-version, Value: 6.0
[INFO] Parameter: package, Value: com.example.modules.foxforcefour
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: module-name, Value: fox-force-four
[INFO] Parameter: artifactId, Value: fox-force-four
[INFO] Project created from Archetype in dir: /Users/jdoe/repositories/magnolia/fox-force-four
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------


Magnolia Maven archetypes

Currently, Magnolia provides the following archetypes:

archetypeArtifactId Meaning
magnolia-project-archetypeCreate a Magnolia webapp project
magnolia-module-archetypeCreate a basic Magnolia Maven module
magnolia-forge-module-archetypeCreate a Magnolia Maven Forge module
magnolia-blossom-module-archetypeCreate a Magnolia Blossom module
magnolia-theme-archetypeCreate a Magnolia STK theme based module

Creating a webapp

The magnolia-project-archetype creates a project with a parent pom and one module defining a Magnolia webapp.

Command

mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE

Required parameters
ParameterExample valueExplanation
Maven groupId com.example

Typically reflects the name or domain of your company or projects.


Maven artifactIdcustom-projectProject-specific identifier.
Maven artifact version1.0-SNAPSHOTProject version. Typically, when creating a new project, use the value suggested by Maven, for example 1.0-SNAPSHOT.
package com.example Package name for Java classes reflecting both your company (or domain) and the specific project.
magnolia-bundle-version6.0

Magnolia version from which your custom project inherits.

project-namecustom-project

Project name.


Generated skeleton
custom-project/
├── custom-project-webapp
│   ├── pom.xml
│   └── src
└── pom.xml

(info) The src directory contains more subfolders. For further details, please read Creating a custom webapp with Maven.

Creating modules

Basic module

The magnolia-module-archetype creates a skeleton for a basic Magnolia Maven module. For details about Magnolia Maven modules, please refer to the Modules page. 

Command

mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-module-archetype -DarchetypeVersion=RELEASE

Required parameters

ParameterExample valueExplanation
Maven groupId com.example Typically reflects the name or domain of your company or projects.
Maven artifactIdfoobar-module Project-specific identifier.
Maven artifact version1.0-SNAPSHOTProject 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-version6.0

Magnolia version from which your custom project inherits.

module-class-nameFoobarModule The Java class name of the autogenerated module class.
project-namefoobar-module

Project name.

Generated skeleton

my-module/
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   └── resources
    └── test
        ├── java
        └── resources
(info) The java and resources directories contain more subfolders. For further details, see Module structure.

Forge module

The magnolia-forge-module-archetype creates a skeleton for a Magnolia Maven Forge module. Forge modules are typically shared among the community. Please refer to the Modules page for more details about Magnolia Maven modules. See also the Forge repositories of the Magnolia Bitbucket server.

This archetype and the skeleton generated are very similar to the magnolia-module-archetype. The main (AND ONLY???) difference is that the generated pom file utilizes the parent pom info.magnolia.maven.poms-forge:magnolia-parent-pom-forge.

Command
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-forge-module-archetype -DarchetypeVersion=RELEASE
Required parameters
ParameterExample valueExplanation
Maven groupId com.example Typically reflects the name or domain of your company or projects.
Maven artifactIdfox-force-four Project-specific identifier.
Maven artifact version1.0-SNAPSHOTProject version. Typically, when creating a new project, use the value suggested by Maven, for example 1.0-SNAPSHOT.
package com.example.modules.foxforcefour Package name for Java classes reflecting both your company (or domain) and the specific project.
magnolia-bundle-version6.0

Magnolia version from which your custom project inherits.

module-class-nameFoxforcefourModule The Java class name of the autogenerated module class.
project-namefox-force-four 

Project name.

Generated skeleton
fox-force-four/
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   └── resources
    └── test
        ├── java
        └── resources

(info) The java and resources directories contain more subfolders. For more details, see Module structure.

Blossom module

The magnolia-blossom-module-archetype creates a skeleton for a Magnolia Blossom module. 

For further details about how to use Magnolia Blossom, please refer to Getting started with Blossom.

Command
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-blossom-module-archetype -DarchetypeVersion=RELEASE
Required parameters
ParameterExample valueExplanation
Maven groupId com.example Typically reflects the name or domain of your company or projects.
Maven artifactIdmy-blossom-module Project-specific identifier.
Maven artifact version1.0-SNAPSHOTProject version. Typically, when creating a new project, use the value suggested by Maven, for example 1.0-SNAPSHOT.
package com.example.modules.blossom Package name for Java classes reflecting both your company (or domain) and the specific project.
blossom-version3.2.1 The version of the Magnolia Blossom module.
magnolia-bundle-version6.0

Magnolia version from which your module project inherits the BOM files managing the versions for third-party dependencies.

module-class-nameMyBlossomModule The Java class name of the autogenerated module class.
project-namemy-blossom-module

Project name.

Generated skeleton
my-blossom-module/
├── pom.xml
└── src
    └── main
        ├── java
        └── resources

(info) The java and resources directories may contain more subfolders. For more details, see Module structure.

STK theme based module

The magnolia-theme-archetype creates a skeleton for a Magnolia STK theme based module.

We don't recommend using this archetype since Magnolia STK reached end of life in December 2018. For more details, see End-of-life policy-Standard Templating Kit (STK).

Required parameters
ParameterExample valueExplanation
Maven groupId com.example Typically reflects the name or domain of your company or projects.
Maven artifactIdmy-stk-theme Project-specific identifier.
Maven artifact version1.0-SNAPSHOTProject version. Typically, when creating a new project, use the value suggested by Maven, for example 1.0-SNAPSHOT.
package com.example.stktheme Package name for Java classes reflecting both your company (or domain) and the specific project.
magnolia-bundle-version5.6.1

Magnolia version from which your custom project inherits.*

magnolia-stk-version3.1.1Magnolia STK version.
theme-namefancy-stk-theme 

Name of the STK theme.

*) Please also check How to create a custom webapp with STK modules to make sure you are using the same magnolia-bundle-version and magnolia-stk-version for both the webapp and the STK theme module.

Generated skeleton
my-stk-theme/
└── src
    └── main
        ├── java
        │   └── com
        │       └── example
        │           └── stktheme
        └── resources
            ├── META-INF
            │   └── magnolia
            └── templating-kit
                └── themes
                    └── fancy-stk-theme
                        ├── css
                        ├── img
                        └── js