Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

This guide will walk you through using archetypes to create a new project that uses Blossom.

Creating the project

First, create a directory on your local file system where the project will be stored and change into this directory.

Then execute the following maven command:

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

This will present you with a prompt where you can choose between the archetypes we provide.

Choose archetype:
1: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-theme-archetype (An archetype to create STK Theme modules)
2: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-project-archetype (An archetype to create a Magnolia project (a parent pom and a webapp))
3: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-module-archetype (An archetype to create basic Magnolia modules)
4: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-forge-module-archetype (An archetype to create a Magnolia module to be hosted on the Magnolia Forge)
5: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-blossom-module-archetype (An archetype to create Magnolia modules using Blossom)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 2
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-SNAPSHOT
Choose a number: 6: 6

We'll go with option magnolia-project-archetype, a Magnolia project with a parent pom and a webapp. It will then ask us for the standard maven properties, which version of Magnolia we'll be using etc.

Define value for property 'groupId': : com.acme.webapps
Define value for property 'artifactId': : acme
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  com.acme: :
Define value for property 'magnolia-bundle-version': : 5.6.5
Define value for property 'project-name':  acme: : acme-project
Confirm properties configuration:
groupId: com.acme
artifactId: acme
version: 1.0-SNAPSHOT
package: com.acme
magnolia-version: 5.6.5
project-name: acme-project
 Y: :

What we have now is a Magnolia project setup that is easily updated and maintained. The project is a maven multi-module setup with a webapp project that builds into a WAR file with Magnolia brought in using maven dependencies.

You can now open the project in your IDE.

The directory structure created looks like this:

Creating your own module

The next step we'll do is create a Magnolia module that we'll use for developing our website. Again the archetypes can help us do most of the work. We'll issue the same command. This time standing in the directory that was created for our project.

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

We're presented with the same options as before.

Choose archetype:
1: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-theme-archetype (An archetype to create STK Theme modules)
2: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-project-archetype (An archetype to create a Magnolia project (a parent pom and a webapp))
3: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-module-archetype (An archetype to create basic Magnolia modules)
4: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-forge-module-archetype (An archetype to create a Magnolia module to be hosted on the Magnolia Forge)
5: https://nexus.magnolia-cms.com/content/groups/public/ -> info.magnolia.maven.archetypes:magnolia-blossom-module-archetype (An archetype to create Magnolia modules using Blossom)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 5
Choose info.magnolia.maven.archetypes:magnolia-blossom-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-SNAPSHOT 
Choose a number: 6

This time we're choosing option magnolia-blossom-module-archetype. Maven again asks us for the standard properties, the Magnolia version to use and also properties for the module.

Define value for property 'groupId': : com.acme.blossom
Define value for property 'artifactId': : acme-blossom-module
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  com.acme.blossom: :
Define value for property 'blossom-version': : 3.2.1
Define value for property 'magnolia-version': : 5.6.5
Define value for property 'module-class-name': : AcmeModule
Define value for property 'module-name':  acme-blossom-module: : acme-blossom
Confirm properties configuration:
groupId: com.acme.blossom
artifactId: acme-blossom-module
version: 1.0-SNAPSHOT
package: com.acme.blossom
blossom-version: 3.2.1
magnolia-version: 5.6.5
module-class-name: AcmeModule
module-name: acme-blossom
 Y: :

This creates a Magnolia module acme-module and adds it to the parent pom. The module has a descriptor file, a module class, and the required folder structure.

Create a dependency

Declare the module as a dependency to the webapp pom. Add the following dependency to the acme-webapp pom.xml:

<dependency>
    <groupId>com.acme.blossom</groupId>
    <artifactId>acme-blossom-module</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Build and Run

We now have a module with a module class, AcmeModule, and a module descriptor file, acme-blossom.xml. There's also an applicationContext.xml for spring beans.

At this point we can build it all using:

mvn clean install

And if we want to start it up using maven we can add the jetty plugin to the webapp's pom file:

<plugin>
  <groupId>org.mortbay.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <scanIntervalSeconds>5</scanIntervalSeconds>
  </configuration>
</plugin>

Then point your browser to http://localhost:8080/acme-webapp/

When the webapp starts up you should see the following output:

2013-10-09 18:47:10,921 INFO  info.magnolia.module.ModuleManagerImpl            : Starting module acme-blossom
2013-10-09 18:47:11,477 INFO  lia.module.blossom.render.BlossomDispatcherServlet: FrameworkServlet 'blossom': initialization started
2013-10-09 18:47:11,995 INFO  .magnolia.module.blossom.template.TemplateExporter: Registered templates [acme-blossom:pages/mainTemplate]
2013-10-09 18:47:11,995 INFO  lia.module.blossom.render.BlossomDispatcherServlet: FrameworkServlet 'blossom': initialization completed in 518 ms

There we are, are complete project ready to load in your IDE!