How to use Magnolia Maven archetypes
This page explains how to use Magnolia-specific Maven archetypes to jumpstart development of Magnolia Maven modules and projects.
Requirements
You need Maven to generate Magnolia project archetypes. To set up Maven, follow the procedure described on our Maven setup page. During the setup, the settings.xml
file is created.
Depending on whether you are a user of the Community Edition or DX Core, check that the file contains the following snippet. If it does not, add it to the file, before the profiles
section.
<mirrors>
<mirror>
<id>magnolia.nexus.public</id>
<url>https://nexus.magnolia-cms.com/repository/public</url>
<mirrorOf>archetype</mirrorOf>
</mirror>
</mirrors>
<mirrors>
<mirror>
<id>magnolia.nexus.enterprise</id>
<url>https://nexus.magnolia-cms.com/repository/enterprise</url>
<mirrorOf>archetype</mirrorOf>
</mirror>
</mirrors>
Update credentials for Maven settings
It’s possible that you may need to update your credentials for Maven settings.
-
Log into Nexus.
-
Go to your profile. This is typically in the top corner with your username.
-
Select User Token from the menu.
-
Click Access user token.
This prompts you to log in again. Upon successful login, your user token is displayed.
-
Optional If you want, you can encrypt your password:
mvn --encrypt-password $passcode
-
Finally, store the token in the format shown here.
<server> <id>magnolia.nexus.enterprise</id> (1) <!-- Token, not actual username / password --> <username>{userTokenNameCode}</username> (2) <password>{userTokenPassCode}</password> (3) </server>
1 The Magnolia enterprise server. 2 Your user token name code from Nexus. 3 Your user token pass code (access token) from Nexus.
The Archetype plugin
The Maven Archetype Plugin allows you to create a Maven project from an archetype – an existing template (a skeleton of files and directories).
The base plugin command is mvn archetype:generate
.
-
For an overview of the parameters it accepts, see the archetype:generate page on the Apache Maven Project website.
-
For details on how the command works and how to use the interactive mode, see the Usage page on the site.
Option A
If you already know which Magnolia archetype you want to generate, the fastest way is to supply the archetype’s Maven coordinates (GAV) to the command line. For example:
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE
If you omit the archetypeVersion , the plugin automatically picks the oldest version.
|
Option B
By default, the archetype plugin collects a list of all possible archetypes, including those found at Maven Central. The list can be very long and it may take some time to generate it. To reduce the list only to available Magnolia archetypes, use the plugin command with the following filter
option:
mvn archetype:generate -Dfilter=info.magnolia.maven.archetypes:magnolia
If you need to interrupt the command, press CTRL + C .
|
Magnolia Maven archetypes
Magnolia provides the following archetypes:
-
The
magnolia-project-archetype
generates a Magnolia project with a parent POM and a Magnolia webapp. -
The
magnolia-module-archetype
generates a Magnolia Maven module. For details, please refer to the Modules page. -
The
magnolia-blossom-module-archetype
generates a Magnolia Maven module with support for the Blossom module. -
The
magnolia-cloud-project-archetype
generates a Magnolia project with both a parent POM and both thedev
andshared
directories. See Creating and deploying custom cloud bundles for more details.
Before generating a project, the archetypes ask you to supply values for the following parameters:
Required parameters | Example value | Notes | ||
---|---|---|---|---|
Maven |
|
Typically reflects the name or domain of your company or projects. |
||
Maven |
|
Project-specific identifier. |
||
Maven |
|
Project version. Typically, when creating a new project, use the value suggested by Maven, for example |
||
|
|
Package name for Java classes reflecting both your company (or domain) and the specific project. |
||
|
|
Magnolia version to be used in your custom project. |
||
|
|
Project name. |
||
|
|
Module name.
|
||
|
|
The version of the Magnolia Blossom module.
|
Discontinued archetypes
As of version 1.2.5
, the following archetypes have been discontinued. Older versions may still appear if you use the filter option.
-
The
magnolia-forge-module-archetype
, used to create a Magnolia module for the former Magnolia Forge (moved to GitHub: Magnolia Forge). -
The
magnolia-theme-archetype
, used to create an STK (deprecated) theme module.
Generated skeletons
A creation of a project typically results in the following skeleton, with a few more files created in src/main/webapp
. For details, see Creating a custom webapp with Maven.
custom-project/
├── custom-project-webapp
│ ├── pom.xml
│ └── src
│ └── main
│ └── webapp
└── pom.xml
On the other hand, if you create a module, the skeleton will have a simpler structure (no multi-module Maven reactor), with a pre-generated Magnolia module descriptor and Java module class. See also Module structure.
custom-module/
├── pom.xml
└── src
├── main
│ ├── java
│ └── resources
│ └── META-INF
│ └── magnolia
│ └── custom-module.xml
└── test