This page provides a quick overview of module development for experienced Magnolia developers.  An overview of Magnolia modules can be found at in our documentation on the Modules  page.


Using a Maven Archetype

You can use Maven 2's archetype plugin to quickly get started with creating a module or project.

Use this command:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public/ 

You will first be prompted to "Choose an archetype".

You will further be prompted for various properties, whose names should hopefully be obvious enough for you to figure what to enter. If not, try some random value, see the results and try again (wink) (Please vote for this maven-archetype-plugin enhancement !)

Module archetype

The module archetype will generate a basic Magnolia module, including all necessary folders, a module descriptor and two classes:

Forge Module archetype

The Forge Module archetype is deprecated.

Please follow these improved tips to create a Forge module: Magnolia Forge#Mavenbuild

STK Theme archetype

The STK Theme archetype will produce a quickstart for an STK Theme (see also the part on themes in STK changes in 5.4).

Project archetype


See the official documentation on how to setup a Maven based Magnolia webapp. 

Tutorial for a community project.

Tutorial for a DX Core enterprise project (requires a licence.)


The Project archetype will produce a skeleton for a "project"; this will contain

  • a parent pom
  • a webapp, overlaying magnolia-empty-webapp, ready to host your custom configuration files.

If you want to add a module to an existing project, generating the module artifact from within your project should get you started quickly, as it will adapt the new artifact's parent pom to match your existing project !

Changing a project from CE to EE

When you create a project using an archetype from the public group you get a Community Edition (CE) project. This means the project has dependencies to the CE bundle and you get only community modules. If you need a more substantial starting point, change the dependencies in your POM files to the Enterprise Edition (EE) bundle and webapp. This way you get enterprise modules such as Multisite and Workflow.

There are two videos in Magnolia Academy that explain how to work with Module Dependencies.

In your project POM, set:

  • groupId: info.magnolia.eebundle
  • artifactId: magnolia-enterprise-bundle-parent

Change this:

CE dependencies in project POM
<dependency>
    <groupId>info.magnolia.bundle</groupId>
    <artifactId>magnolia-bundle-parent</artifactId>
    <version>${magnoliaVersion}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

To this:

EE dependencies in project POM
<dependency>
    <groupId>info.magnolia.eebundle</groupId>
    <artifactId>magnolia-enterprise-bundle-parent</artifactId>
    <version>${magnoliaVersion}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>
  1. fake

In your webapp POM, set:

  • groupId: info.magnolia.eebundle
  • artifactId: magnolia-enterprise-webapp

Change this:

CE dependencies in webapp POM
<dependency>
    <groupId>info.magnolia</groupId>
    <artifactId>magnolia-empty-webapp</artifactId>
    <type>pom</type>
</dependency>
<dependency>
    <groupId>info.magnolia</groupId>
    <artifactId>magnolia-empty-webapp</artifactId>
    <type>war</type>
</dependency>

To this:

EE dependencies in webapp POM
<dependency>
    <groupId>info.magnolia.eebundle</groupId>
    <artifactId>magnolia-enterprise-webapp</artifactId>
    <type>pom</type>
</dependency>
<dependency>
    <groupId>info.magnolia.eebundle</groupId>
    <artifactId>magnolia-enterprise-webapp</artifactId>
    <type>war</type>
</dependency>


Setting the File Encoding

If you see a warning about file encoding:

[WARNING] File encoding has not been set, using platform encoding Cp1252, i.e. build is platform dependent!
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!

See https://maven.apache.org/general.html#encoding-warning for instructions.

Contribute

Have a look at http://jira.magnolia-cms.com/browse/ARCH to see known problems or suggest new features.

Please try it out and tell us what you think !

More info about Maven archetypes:

Host your module at the Forge!

Hey, why not share your new module with the world and host it at the forge?

9 Comments

  1. Giancarlo Berner

    Is there already an Archetype for Modules in Magnolia 4.01 or 4.1?

    1. Magnolia International

      Sorry for the late reply, but yes, finally !
      (you can even choose the Magnolia version when generating(wink))

  2. Jozef Chocholacek

    If you occur an 

    Request to merge when 'filtering' is not identical.

    error when running 

    mvn eclipse:eclipse

    on your newly created module, here is the solution http://forums.atlassian.com/thread.jspa?threadID=34952&tstart=30.

  3. Matt Dertinger

    Way cool beans!

    Love the new archetypes! Thank you Joerg and Greg!

    In case anyone is interested, you may also add the archetypes to your local archetype-catalog as an alternative to passing in the -DarchetypeCatalog=http://nexus.magnolia-cms.com/content/groups/public/ argument.

    To do so:

    1. Make sure you've run through the steps to setup Maven with Magnolia's Nexus Repositories - @see Maven Setup
    2. Under your ~/.m2 check to see if you already have an archetype-catalog.xml file. If not, create one.
    3. Open up archetype-catalog.xml, and add the magnolia archetypes you'd like to use, for instance:
      archetype-catalog.xml
      <?xml version="1.0" encoding="UTF-8"?>
<archetype-catalog 
  xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0 http://maven.apache.org/xsd/archetype-catalog-1.0.0.xsd">
  <archetypes>
    ...
    <archetype>
      <groupId>info.magnolia.maven.archetypes</groupId>
      <artifactId>magnolia-module-archetype</artifactId>
      <version>1.1.0-SNAPSHOT</version>
      <description>An archetype to create basic Magnolia modules</description>
    </archetype>
    <archetype>
      <groupId>info.magnolia.maven.archetypes</groupId>
      <artifactId>magnolia-forge-module-archetype</artifactId>
      <version>1.1.0-SNAPSHOT</version>
      <description>An archetype to create a Magnolia module to be hosted on the Magnolia Forge</description>
    </archetype>
    <archetype>
      <groupId>info.magnolia.maven.archetypes</groupId>
      <artifactId>magnolia-theme-archetype</artifactId>
      <version>1.1.0-SNAPSHOT</version>
      <description>An archetype to create STK Theme modules</description>
    </archetype>
    <archetype>
      <groupId>info.magnolia.maven.archetypes</groupId>
      <artifactId>magnolia-project-archetype</artifactId>
      <version>1.1.0-SNAPSHOT</version>
      <description>An archetype to create a Magnolia project (a parent pom and a webapp)</description>
    </archetype>
  </archetypes>
</archetype-catalog>
    4. Save the file, open up a terminal, and run: 
      $ mvn archetype:generate
    5. You should see the magnolia archetypes in the list of available archetypes to choose from
    6. Enjoy!

    1. Magnolia International

      True, but that'd mean maintaining that list (new archetypes, new versions, ...) - whereas our catalog is always up-to-date. (generated by Nexus).

  4. joshua portway

    In case it will be of help to anyone else - there are currently a couple of severe bugs in the magnolia 5 maven project archetype which will cause a lot of frustration for anyone trying to create a new project.

    the first problem is that the project pom omits a dependency of the Vaadin repository. As a result if you create a project from the archetype and attempt to build it the build will fail with an error like this :

    The POM for org.vaadin.addons:icepush:jar:0.5.3 is missing, no dependency information available
    The POM for org.vaadin.addons:cssinject:jar:2.0.3 is missing, no dependency information available
    The POM for org.vaadin.addons:gwt-graphics:jar:1.0.0 is missing, no dependency information available
    The POM for org.vaadin.addons:ckeditor-wrapper-for-vaadin:jar:7.8.3 is missing, no dependency information available
    The POM for org.vaadin.addon:easyuploads:jar:7.0.0 is missing, no dependency information available
    The POM for org.vaadin.addons:refresher:jar:1.2.1.7 is missing, no dependency information available

     

    The solution is to to add this to the repositories section of the project POM :

    vaadin repository reference
    <repository>
	<id>vaadin-addons</id>
	<url>http://maven.vaadin.com/vaadin-addons</url>
</repository>

    The other problem is that Maven will complain about a missing version number for the maven-war-plugin - I'm not sure whether this has any real effect on the build, but it causes a warning to be issued for every build,  like this :

    Some problems were encountered while building the effective model for stain.org:rocamoraSite-webapp:war:1.0-SNAPSHOT
    'build.plugins.plugin.version' for org.apache.maven.plugins:maven-war-plugin is missing. @ line 30, column 21

    To sort this out, just add a version number property to the maven war plugin reference in the pom file within the web app sub folder like this :

    war plugin version number
    <plugin>
	<artifactId>maven-war-plugin</artifactId>
	<version>2.4</version>
	<configuration>
	<!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
	<dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
	</configuration>
</plugin>

     

    Hopefully, when these problems are sorted out an admin can delete this comment....

    1. Magnolia International

      Joshua,

      Thanks for this - we track issues with the archetypes on Jira: ARCH

      The first problem is well known and should already be in there. Just got no time so far to fix it. (In part because it won't be necessary to have that fix everywhere, and in part because I've been wondering why Vaadin add-ons are not mirrored on Maven Central)

      The second problem is probably specific to Maven 3, we still use Maven 2.2, which is why we haven't seen it yet. However you're right, and it's generally good practice to add plugin version numbers in any case. It's the type of thing that people will configured via their "corporate" parent pom, though.

  5. Espen Jervidalo

    There's a dependency problem related to Admin Interface Legacy Module (version 5.0.2)  using Version 1.1 of the archetype together with Magnolia 5. Use the latest 1.2-SNAPSHOT to get it running properly. The final version 1.2 is going to be released soon.

  6. Pete Ryland

    Please note that https must be used to access nexus now.