Getting started with Blossom

getting started with Blossom

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

Creating the project

Before running the Maven archetype command, please read How to use Magnolia Maven archetypes: Check Maven settings.

Take note of the versions of Magnolia and the Blossom module in the configurations below. In this tutorial, we always try using the latest versions.

On your local file system, create a new directory for the project, change into the directory and execute the following Maven command:

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

Maven prompts you to specify values for several parameters. Use values that fit your requirements. NOTE: Take a note of the value you enter for the magnolia-bundle-version property. You will need it later on to create your own module.

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.webapps: :
Define value for property 'magnolia-bundle-version': 6.2
Define value for property 'project-name' acme: : acme-project
Confirm properties configuration:
groupId: com.acme.webapps
artifactId: acme
version: 1.0-SNAPSHOT
package: com.acme.webapps
magnolia-bundle-version: 6.2
project-name: acme-project
 Y: :

The result you get is an easy to update and maintain Magnolia project. The project is a Maven multi-module setup, with a webapp building into a WAR file. The file contains Magnolia, which is brought in using Maven dependencies.

You can open the project in your IDE. The directory structure created looks like this:

acme
├── acme-webapp
│ ├── pom.xml
│ └── src
│ └── main
│ └── webapp
│ ├── WEB-INF
│ │ ├── bootstrap
│ │ │ ├── author
│ │ │ ├── common
│ │ │ └── public
│ │ └── config
│ │ └── default
│ └── docroot
└── pom.xml

Creating your own module

In this step, you create a Magnolia module to be used to develop your website. The archetypes can help you do most of the work.

In the project directory, issue the following command:

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

Maven asks you again to supply some property values.

For the magnolia-bundle-version, enter the value you have used above when creating the project.
For the blossom-version, use the latest version, currently at [$version]([("artifactId","magnolia-module-blossom"),("groupId","info.magnolia.blossom"),("label","$version"),("renderType","display_only"),("resourceType","POM")]).
WARNING: If you are using older Magnolia versions, you may have to use older Blossom versions. If you cannot decide which version to use, contact our support or check the Magnolia Developers Mailing List.

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.3.1
Define value for property 'magnolia-bundle-version': 6.2
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.3.1
magnolia-bundle-version: 6.2
module-class-name: AcmeModule
module-name: acme-blossom
 Y: :

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

acme-blossom-module/
├── pom.xml
└── src
    └── main
        ├── java
        │ └── com
        │ └── acme
        │ └── blossom
        │ ├── AcmeModule.java
        │ ├── config
        │ │ ├── AcmeModuleConfiguration.java
        │ │ ├── BlossomServletConfiguration.java
        │ │ ├── FreemarkerRenderingConfiguration.java
        │ │ ├── JspRenderingConfiguration.java
        │ │ └── SiteAwareFreemarkerRenderingConfiguration.java
        │ └── setup
        │ └── AcmeModuleVersionHandler.java
        └── resources
            ├── META-INF
            │ └── magnolia
            │ └── acme-blossom.xml
            ├── acme-blossom
            │ ├── components
            │ └── pages
            ├── applicationContext.xml
            ├── blossom-servlet.xml
            ├── mgnl-bootstrap
            │ └── acme-blossom
            │ └── config.modules.site.config.site.xml
            ├── mgnl-files
            │ ├── docroot
            │ │ └── acme-blossom
            │ └── templates
            │ └── acme-blossom
            │ ├── components
            │ └── pages
            └── mgnl-resources
                └── acme-blossom

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

You now have a module with:

A module class, AcmeModule.
A module descriptor file, acme-blossom.xml.

Also present is the applicationContext.xml for Spring beans.

To build it all, cd to acme/* and enter the following command:

mvn clean install

If you want to use Maven to start it up, 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/.

After the webapp has started, you should get the following output:

INFO info.magnolia.module.ModuleManagerImpl : Starting module acme-blossom
INFO lia.module.blossom.render.BlossomDispatcherServlet: FrameworkServlet 'blossom': initialization started
INFO .magnolia.module.blossom.template.TemplateExporter: Registered templates [acme-blossom:pages/mainTemplate]
INFO lia.module.blossom.render.BlossomDispatcherServlet: FrameworkServlet 'blossom': initialization completed in 518 ms

There you go. The project is ready to be loaded in your IDE.

Feedback

DX Core

Getting started with Blossom