Page History
HTML Wrap | ||||
---|---|---|---|---|
| ||||
Related topics:
Apache Maven documentation:
|
This page explains how to use Magnolia-specific Maven archetypes to jumpstart various Magnolia development tasks related to of Magnolia Maven modules and projects.
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 Project: Introduction to Archetypes)
Info |
---|
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. |
Table of Contents | ||||
---|---|---|---|---|
|
...
Requirements
Maven
Tip |
---|
If you want to generate a Magnolia Cloud project archetype to create a custom cloud bundle, see Creating and deploying custom cloud bundles. |
Table of Contents | ||||
---|---|---|---|---|
|
Requirements
You need Maven to generate Magnolia project archetypes. To setup Maven, follow 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..
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
sectionOpen 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.
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
| |||||
Expand | |||||
| |||||
|
...
The archetype plugin
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 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
...
).
Info |
---|
The base plugin command is
|
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:
Here is the base command without any parameter:
Code Block | ||
---|---|---|
| ||
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
.
Tip | ||
---|---|---|
| ||
To interrupt the |
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
.
Code Block | ||
---|---|---|
| ||
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 |
Sometimes, Maven prompts you to enter a literal value such as com.example
and confirm with ENTER
:
Code Block | ||
---|---|---|
| ||
Define value for property 'groupId': |
...
Choosing an archetype version
Note | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
We highly recommend that you use the latest released archetype version or the SNAPSHOT version. Avoid using old versions. If you call the plugin with the Use the command in a form that lets you specify the archetype version. You can use Currently, the latest released version is |
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:
Code Block | ||
---|---|---|
| ||
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE |
List of available archetypes
If If you omit the archetypeVersion
, the plugin automatically picks the oldest version.
Option B
By default, the archetype plugin collects both the archetypeGroupId
and the archetypeArtifactId
, the plugin collects a list of all possible archetypes. Be aware that the , including those found at Maven Central. The list can be very long and it may take some time to generate it.
Note |
---|
Depending on your internal Maven |
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:
Code Block | ||
---|---|---|
| ||
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 To reduce the list only to available Magnolia archetypes, use the plugin command with the following filter
option:
Code Block | ||
---|---|---|
| ||
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.
Expand | |||||
---|---|---|---|---|---|
| |||||
|
...
If you need to interrupt the command, press CTRL + C
.
Which Magnolia archetype to use?
...
Magnolia Maven archetypes
Currently, 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.
Before generating a project, the archetypes ask you to supply values for the following parameters:
Required parameters |
---|
Tip |
---|
See Apache Maven Project's Guide to naming conventions on groupId, artifactId, and version. |
...
Creating a webapp
The magnolia-project-archetype
creates a project with a parent pom and one module defining a Magnolia webapp.
Command
Multiexcerpt | |||||
---|---|---|---|---|---|
| |||||
|
Required parameters
Example value | Explanation | |
---|---|---|
Maven groupId | com.example | Typically, it reflects the name or domain of your |
organization. | ||
Maven artifactId | custom-project | Project-specific identifier. |
Maven version | 1.0-SNAPSHOT | Project version. |
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 |
organization and the specific project. | |
magnolia-bundle-version | 6. |
1 | Magnolia version |
to be used in your custom project |
. |
project-name |
custom-project
Project name.
...
Code Block |
---|
custom-project/
├── custom-project-webapp
│ ├── pom.xml
│ └── src
└── pom.xml |
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
Multiexcerpt | |||||
---|---|---|---|---|---|
| |||||
|
Required parameters
...
MultiExcerptName | required-params_module |
---|
...
Magnolia version from which your custom project inherits.
...
Project name.
Custom Project | A human-readable version of the | |
Additional parameters | ||
module-class-name | FoobarModule | The Java class name of the generated module class (for module archetypes only). |
blossom-version | 3.2.1 | The version of the Magnolia Blossom module (for the blossom module archetype only). |
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.
Anchor | ||||
---|---|---|---|---|
|
Which archetype version should I use?
Use the latest archetype release:
. Exceptionally, Enterprise Edition projects for use with Magnolia 5.7 or lower should be generated with version Artifact resource link groupId info.magnolia.maven.archetypes artifactId magnolia-archetypes-parent label $version renderType display_only resourceType JAR 1.2.4
.
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.
Code Block |
---|
custom-project/
├── custom-project-webapp
│ ├── pom.xml
│ └── src
│ └── main
│ |
Generated skeleton
Multiexcerpt | ||
---|---|---|
| ||
|
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
Code Block | ||
---|---|---|
| ||
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-forge-module-archetype -DarchetypeVersion=RELEASE |
Required parameters
...
Magnolia version from which your custom project inherits.
...
Project name.
Generated skeleton
Code Block |
---|
fox-force-four/ ├── pom.xml └── src ├── main │ ├── java │ └── resources └── test ├──└── java └── resources |
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
Code Block | ||
---|---|---|
| ||
mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-blossom-module-archetype -DarchetypeVersion=RELEASE |
Required parameters
...
Magnolia version from which your module project inherits the BOM files managing the versions for third-party dependencies.
...
Project name.
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.
Code Block |
---|
custom |
Generated skeleton
Code Block |
---|
my-blossom-module/ ├── pom.xml └── src └── main ├── java └── resources |
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.
Note |
---|
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
...
Magnolia version from which your custom project inherits.*
...
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
Code Block |
---|
my-stk-theme/ └── src └── main │ ├── java │ └── comresources │ │ └── example │ └── stktheme └── resources ├── └── META-INF │ │ └── magnolia │ └── templating-kit └── themes └── fancy-stk-theme ├── css ├── img custom-module.xml └── jstest |