Page History

HTML Wrap

align	right
class	menu

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

maxLevel	3
minLevel	2

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

title	For CE usersCommunity Edition

Code Block

language	xml

  <mirrors>
    <mirror>
      <id>magnolia.nexus.public</id>
      <url>https://nexus.magnolia-cms.com/content/groups/public</url>
      <mirrorOf>archetype</mirrorOf>
    </mirror>
  </mirrors>

Expand

title	For forge users

Code Block

language	xml

  <mirrors>
    <mirror>
     <id>magnolia.nexus.public</id>
     <url>https://nexus.magnolia-cms.com/content/groups/public</url>
     <mirrorOf>archetype</mirrorOf>
    </mirror>
  </mirrors>

Expand

title	For DX Core users

Code Block

language	xml

  <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

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 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

Here is the base command without any parameter:

Code Block

language	text

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

title	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.

Code Block

language	text

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:

Code Block

language	text

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 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

Artifact resource link

groupId	info.magnolia.maven.archetypes
artifactId	magnolia-archetypes-parent
label	$version
renderType	display_only
resourceType	JAR

.

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

language	text

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 `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:

Code Block

language	text

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

language	text

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

title	Click to see an example of the confirmation dialog.

Code Block

language	text

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:

...

If you need to interrupt the command, press CTRL + C.

Which Magnolia archetype to use?

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

MultiExcerptName	direct-command_webapp

Code Block

language	text

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

Required parameters

Parameter

	Example value	Explanation
Maven `groupId`	`com.example`	Typically, it reflects the name or domain of your

company or projects

organization.
Maven `artifactId`	`custom-project`	Project-specific identifier.

Maven artifact

Maven version 1.0-SNAPSHOT Project version.

Typically, when

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)

organization and the specific project.
`magnolia-bundle-version`	`6.`

0

`1`	Magnolia version

from which

to be used in your custom project

inherits

.

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

MultiExcerptName	direct-command_module

Code Block

language	text

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

Required parameters

...

MultiExcerptName	required-params_module

...

Magnolia version from which your custom project inherits.

`Custom Project`	A human-readable version of the `artifactId`, Title case and spaces are allowed.
Additional parameters
`module-class-name`	`FoobarModule`	The Java class name of the

...

generated module class

...

Project name.

(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

	anc-choosing-archetype-version
	anc-choosing-archetype-version

Which archetype version should I use?

Use the latest archetype release:

Artifact resource link

groupId	info.magnolia.maven.archetypes
artifactId	magnolia-archetypes-parent
label	$version
renderType	display_only
resourceType	JAR

. Exceptionally, Enterprise Edition projects for use with Magnolia 5.7 or lower should be generated with version 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 │

Generated skeleton

Multiexcerpt

MultiExcerptName	generated-skeleton_module

Code Block
my-module/ ├── pom.xml └── src ├── main │ ├── java │ └── resources └── test ├── java └── resources

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

language	text

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.

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

Command

Code Block

language	text

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.

Generated skeleton

Code Block
my-blossom-module/ ├── pom.xml └── src └── main │ ├── java └── webapp └── 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.

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-module/ ├── pom.xml

*) 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

Page tree

Page History

Versions Compared

Old Version 1

New Version Current

Key

Requirements

Maven

Requirements

Check Maven settings

The archetype plugin

The Archetype plugin

Option A

The interactive mode

Choosing an archetype version

Choosing an archetype

Using the archetype group ID, artifact ID and version

List of available archetypes

Option B

Filtering in the interactive mode

Filtering with parameters

Confirming and finishing

Magnolia Maven archetypes

Which Magnolia archetype to use?

Creating a webapp

Command

Required parameters

Creating modules

Basic module

Command

Required parameters

Discontinued archetypes

Which archetype version should I use?

Generated skeletons

Generated skeleton

Forge module

Command

Required parameters

Generated skeleton

Blossom module

Command

Required parameters

Generated skeleton

STK theme based module

Required parameters

Generated skeleton