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.