How to use Magnolia Maven archetypes

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)

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.

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

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

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

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.

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

Define value for property 'groupId':

Choosing an archetype version

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.

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.

Confirm properties configuration:
groupId: com.example
artifactId: fox-force-four
version: 1.0-SNAPSHOT
package: com.example.modules.foxforcefour
magnolia-bundle-version: 6.2
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.2
[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:

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

Generated skeleton

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

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

Required parameters

Generated skeleton

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

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

Generated skeleton

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

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

Required parameters

Generated skeleton

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.

Required parameters

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