Skip to end of metadata
Go to start of metadata

The Blossom module is the Spring integration for Magnolia CMS. Blossom enables you to create editing components that display a high level of dynamic behavior. These components can be used by editors to create truly interactive web pages. For example, the Spring Framework application stack makes it easier to develop integrations with business systems, so that they fetch the information that you want to present in your pages. As Blossom is built on the Spring Web MVC, familiarity with this framework will ensure a smooth experience working with the module.

Key Blossom functionality

  • Annotation based API that builds on the Spring Web MVC. The Blossom API automatically detects annotated classes and registers them for use in Magnolia. To do this, simply add @Template to your controllers and they are ready to be used as building blocks by editors.
  • Exposes controllers as templates and components, allowing you to use the controller for building a model. Useful if you need to call a web service for information that you need to present or if you need to read information from a database.
  • Template based. Having templates (pages, areas and components) backed by an MVC framework has the benefit of providing natural web development business logic.
  • Enable the re-use of previously created controllers.
  • Allows you to create dialogs with code rather than configuration. This has many benefits:
    • you can populate the dialog at runtime with options detected at runtime:
    • you can obtain dialogs from the repository and place into your source control (CVS, SVN, GIT).
  • Components can be executed in front of Magnolia CMS. This means that it can choose to do a redirect and skip page rendering. This is very useful, for instance, if you have a form that on post should either present an error message or do a redirect.

(warning) Blossom 3.0+. If you are working with an earlier version of Blossom, see Blossom 2.0 documentation or Blossom 1.2 documentation.

Minimum Requirements

  • Blossom requires Magnolia CMS 5.1 or later.
  • Needs at least Java 6.
  • Supports Spring Framework 3.1 or later.


Download the Blossom module from our Nexus repository. Versions prior to 3.0 are stored under a different groupId here.


Blossom is a Community Edition module. It is typically not installed and needs to be downloaded. 

 Click for installation steps...

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Maven users can find the artifact in the magnolia maven repository. For instructions see Maven setup on the wiki.


 Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia CMS.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Getting Started

Programming model

Blossom is an annotation based API that's used in combination with Spring MVC. This snippet gives an overview of how the API is used.

Running the sample project

This sample is a complete web application based on Magnolia 4.5 and requires nothing more than a Maven installation.

  1. Clone the git repository, switch to the right branch, build the project and then run magnolia-blossom-sample-webapp using mvn jetty:run-war.
  2. When maven has downloaded the necessary artifacts and started the application point your browser to localhost:8080.
  3. Magnolia will now be in install mode and display a list of modules for install.
    Complete the installation wizard and then log in using superuser for both username and password.

The sample web app uses JSP EL 2.2 bundled with Servlet API 3.0, use Tomcat 7+ or another servlet container of the same standard compliance level.

Creating your own project

We recommend using the archetypes to create your own project. For more details see this Getting started with Blossom.

What's new in Blossom 3

Major update for Magnolia 5 style dialogs, compatible with Magnolia 5.1 and later. In version 5 Magnolia has a brand new user interface and with it comes a new API for dialogs. This version of Blossom is an update for this API and also contains a few other improvements.

Fluent builder style API for dialogs

Building dialogs is now done using a fluent builder style API with a very compact syntax. The builders allow for controlling every detail of how a field should appear and behave. Where in the old API you had to resort to configure the controls using key and value pairs the new API has chainable setters for every property.

Meta-annotations for component availability

Components can be categorised using custom meta-annotations, these can then be specified when setting the available components on areas. All components having this component category will be available in the area.

Support for autowiring in RenderingModels

AbstractAutowiredRenderingModel is an abstract class for RenderingModels that need be to be autowired using Spring.

Support for Spring MVC 3.1 MVC handler methods

In Spring MVC 3.1 the implementation of annotated MVC was reimplemented adding new handler adapters and handler mappings, starting with Blossom 3.0.2 handlers detected using the new implementation are discovered.

Post processing callbacks prior to registration of templates, areas, components and dialogs

Blossom 3.0.2 introduced a new annotation @PreRegister to be used on methods that should be called prior to registration with Magnolia.

Auto generation of components in areas

The process of auto generation gives areas the opportunity to pre-populate areas with components to save editors some work.

What's new in Blossom 2

Major update for Magnolia 4.5 and its new rendering engine, page editor and templating concepts. The term paragraph is replaced with component. Components and templates have been streamlined and are internally identical, the only real difference is that they have different id formats which in turn controls where they're applicable.

New id conventions for templates

In Magnolia 4.5 template IDs are in the format of <moduleName>:<path>. (See the Templates documentation.) As a consequence the Blossom convention was updated. You now need to specify the ID explicitly on your controller: @Template(id="myModule:pages/news", title="News").

For help on how to migrate your templates to the new naming convention, see Migrating content when upgrading to Blossom 2.


With Magnolia 4.5 areas are explicit entities rather than implicit as node collections. They're declared as nested classes (public static) directly within the page templates they belong to.


This is the reference documentation for Blossom. The sample code in this section uses Spring 2.5+ annotated controllers.


To make a controller function as a template, simply add the @Template annotation. For example:

This controller will be exposed in Magnolia, showing up as 'Section Template'. Note that the 'id' follows a convention used in Magnolia: module name, followed by a path. For templates that you want to use for pages, the path needs to start with pages.

Controlling where a template can be used

To limit the template pages available for editors to use, simply use @Available annotation. Use this on a method in your controller that must return boolean. It can receive as arguments an argument of type Node or Content, this is the page in the website for which to determine if the template is available. It can also accept an argument of type TemplateDefinition this is the internal definition used by Magnolia:


Areas are defined using nested classes (public static class) within a template or within an other area. Areas are standard Spring Web MVC controllers annotated with @Area.  In addition Areas have their own dialog.

Controlling which components can be added to an area

To specify which components can be used in an area you can either list the ids of the components using the @AvailableComponents annotation, list their classes using the @AvailableComponentClasses annotation, or use meta-annotations to categorise your components. It's possible to use all three options on the same area. Meta-annotations are annotations that you create yourself and use on your components. They need to annotated with @ComponentCategory.

This annotation is a component category annotation.

Any controller annotated with it will be included in an area that specifies it.

Area inheritance

A common requirement is to have every page on a site or a whole section to have a consistent base look, sharing header, footer and banners. Area inheritance is a feature that makes an area include components from its parent pages. To use this feature use the @Inherited annotation on an area. 

By default the annotation is set to filtered mode, where it will only include components explicitly marked to be inherited. This is done using a property named inheritable. To flag it the component needs to have a checkbox added to its dialog.

Filtering mode can be turned off causing all components to be inherited.

The annotation also allows you to control how properties are inherited. These are properties on the area itself. A property set on the area in the parent page is then available when the area is rendered in the child page.

Maximum number of components in area

Sometimes its helpful to limit the number of components an editor can add into an area. On the area annotation you can specify the limit your design requires.

Auto generation

To reduce the effort needed by editors to create pages it can be useful to pre-populate pages by automatically adding (generating) components in areas. To use this feature add a method on your area and annotate it with @AutoGenerator. It will receive the Node for the area content.


Components are controllers annotated with @Template and having an id in the format moduleName:components/*.

This controller will be visible as the Text and Image component. The description set using @TemplateDescription is shown when you choose a component to add in the page editor.


Blossom allows you to create dialogs using code. One of the benefits of this is that when the controller fetches data from a web service you can populate your dialog with options retrieved from that web service. See also Dialogs.

For example, if the controller displays a list of the best selling books in a category of books you could call the web service to find out what categories are available and use them to populate a select control. Another benefit is that you get your dialogs out of the repository and into version control. You get to version your dialogs together with your controllers.

You can easily change your dialog code in your IDE, compile and hot swap the new code into an instance of Magnolia CMS running in debug mode. This makes developing dialogs extremely fast.

Fluent builder style API

Dialogs are described using a model of definition classes. These define the structure of the dialog, its tabs and its fields. They describe both what the dialogs and its forms should look like and how they should behave. Blossom uses a fluent builder style API to construct these definitions. The API consists of config classes that produce builders, the builders produce definitions.

The central config class is UiConfig which is used to create tabs and all different kinds of fields provided by Magnolia CMS.

Blossom provides UiConfig to all methods that create dialogs or populate dialogs. In addition it will also provide a TabBuilder or DialogBuilder, depending on the use case. These represent the tab or dialog that's being populated.

Note that is also possible to extend the dialog creation mechanism in Blossom to use custom config classes or replace UiConfig or TabBuilder with classes of your own for adding your custom or third-party fields. The article Extending the Blossom TabBuilder on the wiki explains how this is done in detail.

Dialog factories

Dialog factories create dialogs. Although the dialogs are automatically exposed in Magnolia, you need to configure them as beans in Spring. The easiest way to do this is to use Spring 2.5+ component scan, however manual configuration in XML will work. For example:

This registers a dialog in Magnolia with the name front-page-dialog. It has two tabs, Content and Margins. The order that the dialogs appear in has been set using the @TabOrder annotation. Methods annotated with @TabFactory in superclasses will be called. If there are many dialogs that look the same you can create an abstract base class for them.

Templates create their own dialog

A template always has a dialog so you don't have to create a dialog factory and link them with a name. Instead your controller will act as its own dialog factory. You can use the same annotations inside your controller that you can for dialog factories. (See above.) If you want your template to use a dialog that is created by a dialog factory or configured in the repository, it's possible to override this behavior and specify which dialog should be used:

Templates can contain dialog factories

Because templates are often designed for use with few dialogs, Blossom allows you to create these within your template class for ease of location. The concept is similar to dialog factories but here everything is done in a single method.

Validating dialog input

To ensure that the content is correctly structured you can add validators to the fields. In the example below the name field can not be empty and the email has to be valid.

Using DAM fields

The DAM module has a config class of its own, DamConfig, Blossom also provides this automatically when added as an argument.

Accessing content in controllers

In controllers you can have the content object passed directly to your method. In templates this is the content object for the page, in components it's the content object for the component within the page. If you declare two arguments of type Content or Node the first one will be the content of the page and the second will be the content of the component. Other arguments supported are AggregationStateContextWebContextUser and MgnlUser:

To do this, configure the BlossomWebArgumentResolver on your AnnotationMethodHandlerAdapter.

View rendering

View rendering with Blossom is performed by Spring. Blossom comes with support for using the rendering chain in Magnolia both for JSPs and Freemarker. It works by having view resolvers that return views that call into Magnolia. As a result you'll have access to all the objects that Magnolia provides to template scripts.

Blossom also provides a convenient way of returning redirects to content. By adding the UuidRedirectViewResolver you can return the uuid to redirect to directly from your controller. This example returns a redirect to a page:

This example returns a redirect for a resource in the documents repository:

Redirecting to the page currently being rendered is a very common case and Blossom has a shortcut syntax that does exactly this without requiring the uuid.

It's also possible to redirect to the current content being rendered when executing further down the content hierarchy.

Substituting Blossom view resolvers with custom resolvers

If you substitute or combine the Blossom view resolvers with your own implementations, be aware that the GZip filter included in Magnolia wraps the response object and gives it some non-standard semantics. It will tell you that the response is not committed even though it has been written to. It will also allow you to do redirects even though the response has been written to.

Be aware that if you write controllers that exploit the GZip filter, you are creating a dependency and you will need to have the GZip filter active. Certain framework code, such as the JSP view rendering in Spring and WebFlow will test if the response is committed to detect if redirects are possible and sometimes to choose between doing a forward or an include.

Post processing callbacks prior to registration of templates, areas, components and dialogs

Before Blossom registers templates, areas, components and dialogs with Magnolia at startup, effectively making them available for use, it will inspect its class for methods annotated with @PreRegister and invoke those methods. This can be used to customize the definition Blossom built based on the annotations present on the class.

@PreRegister in template or component
@PreRegister in area
@PreRegister in dialog

Pre-execution of components

Pre-execution allows you to write components that can take care of the entire page rendering. This is necessary if you want to do redirects. Another scenario is if you want to have your controller rendering a form into the page on GET requests and write an XML document or a PDF on POST requests.

Note that this feature is enabled by default from version 1.1 and disabled by default in 0.5. To enable it you need to change a flag in the repository. Navigate to config:/server/filters/blossom in AdminCentral and change the property enabled from 'false to 'true'.

In order for pre-execution to work you need to use the BlossomHandlerMapping. See section on this page on Handler Mapping.

Pre-execution is performed by a filter that will intercept requests and look for a request parameter that contains the UUID of the component that is to be pre-executed. The request parameter is named _pecid. Blossom provides a taglib to make it easier to include this request parameter.

The blossom taglib has two tags, <blossom:pecid-input /> that will output <input type="hidden" name="_pecid" value="<component uuid>" />. This tag is also available under the alias <blossom:pecidInput />, this is necessary for use in Freemarker templates.

It is possible to use <blossom:pecid var="pecid" /> to set the UUID of the component as a variable, in this example named pecid. The var attribute is optional. If it's not specified the component UUID is written directly into the page.

At the end of this article you'll find a full example of how to use pre-execution.

Handler Mapping

Spring uses HandlerMappings to map a request to a handler (usually a controller). Blossom interrogates the HandlerMappings to find out how you have mapped your handlers. Your HandlerMapping needs to be a class inherited from AbstractUrlHandlerMapping. This is usually the case, both Spring 2.5+ annotated controllers and BeanNameUrlHandlerMapping inherit from AbstractUrlHandlerMapping.

If you want support for pre-execution (see below) you will need to have BlossomHandlerMapping delegate to your HandlerMapping. This is necessary because this is where pre-execution is taken care of.

Note, you have to explicitly declare your HandlerMapping in XML. Although Spring will supply you with defaults even if you do not use XML, it is not possible for Blossom ot get a reference to the defaults and therefore will not take part in the rendering.


Using @I18nBasename you can set the name of the resource bundle you want to use. This can be used on templates, areas and components and in dialog factories. Labels and descriptions set for instance using the @Template and @TabFactory annotations will then be localized using the specified resource bundle.

Blossom provides you with a LocaleResolver to enable Spring to pick up the locale that Magnolia has selected for the current request:

To bridge Magnolia i18n into Spring, use the following MessageSource implementation:

If the content of a tab field should be translatable then it can be made i18n aware by using the i18n() method


Multipart Requests

Because Magnolia handles multipart requests, Blossom provides a MultipartResolver implementation. Add this snippet to your beans XML. In the example above this would be blossom-servlet.xml.

Virtual URI Mappings

Any bean implementing VirtualUriMapping that is configured with Spring is automatically detected and exposed in Magnolia. This means that you don not need to configure them in the repository as you normally would.

In addition, Blossom supports writing virtual URI mappings by annotating a class with @VirtualURIMapper. Instances of this class, when configured as a bean in Spring, will be scanned for methods that can be used for URI mapping. Any method that return String or MappingResult and accepts as arguments a String that is the incoming URI or a HttpServletRequest is used.

The returned string from a Virtual URI mapping is the new URI that Magnolia will use to look up the page in the repository that is to be rendered. The returned URI can also be prefixed with "redirect:", "permanent:" or "forward:" to trigger either a temporary redirect, a permanent redirect or a forward respectively. For redirects the URI can be absolute or relative within the web application (the context path is added automatically).

For more details the reference documentation on Virtual URI mapping.

Dependencies on Magnolia components

Magnolia CMS is not based on Spring, but rather uses a container internally that manages components. It is possible to pull these components in as beans in the ApplicationContext. Here they are made available for declaring dependencies on them and as candidates for autowiring. This is an example that exposes the ModuleManager as a bean with id 'moduleManager':

Configuring beans in the repository

Besides for storing content for web pages, the JCR repository is also widely used for configuration. One benefit of this is that configuration is easy to change while the application is running.

To read this configuration Magnolia uses a mechanism called Node2Bean to transform the configuration into plain Java beans. The process is based on reflection. Blossom provides an extension to this mechanism which, during initialization of the bean, applies post processing on it using the Spring ApplicationContext.

This makes it possible to have dependencies in the bean that should be autowired by the ApplicationContext. Note that the bean will also receive all the standard life cycle callbacks that a bean managed by Spring can use. These include:

  • InitializingBean,
  • ServletContextAware,
  • ApplicationContextAware
  • and many more.
    It can also use @PostConstruct and it will be subject for having AOP aspects applied.

The Node2Bean mechanism by default calls a method with the signature public void init() on the beans it creates if it exists. The extension provided by Blossom does not support this. Instead use @PostConstruct.

With Blossom it is possible to use this mechanism directly in Spring beans xml files. The bean is proxied and is transparently replaced if changes are made in the repository.

This is an example for a book store web site that has a discount service configured in the repository:

This example is identical to the one above except that the configuration is observed for any changes being made. When it changes the bean is reloaded making it easy to change the discounts while the system is running:

By default the proxy is created using JDK dynamic proxies, this proxies on an interface level. If you require proxying on the class you can specify proxy-target-class="true" and the proxy will instead be a cglib class proxy. This is analogous to the way Spring AOP uses proxies.

In order to use this you will need to have annotation config enabled in your root web application context. Add the following to your applicationContext.xml.


Using pre-execution

This is a simple controller that displays a form:

The JSP for this component uses the blossom taglib to add the request parameter.

Using Spring WebFlow inside Magnolia

It is possible to include a webflow as a component and embed it into a page. The example below is a controller that exposes a booking flow:

Note that you need to turn off the redirectOnPause behavior since it's not usable when the flow is embedded in a page. Also, you might want to customize the handling of NoSuchFlowException.

Version Repository and Release Notes

Version 3.0.4

Minor update that adds support for setting the node creation flag on areas, and for flash attributes when using
placeholder and uuid redirects. To enable flash support the standard RequestMappingHandlerAdapter has to be replaced
with the specialized BlossomRequestMappingHandlerAdapter. For more details see


  • BLOSSOM-181 Flash attributes not working with uuid redirects

  • BLOSSOM-189 BlossomDispatcherServlet should implement all DispatcherServlet constructors
  • BLOSSOM-191 Area annotation should also support area node creation flag


We'd like to thank everyone that has invested time in testing and providing feedback. Special thanks goes out to
Frank Sommer and Andreas Antener.

Source cross-reference
Source repository

Version 3.0.3

Adds compatibility with DAM 2.x, a short-hand syntax for redirecting to the current content and adds a flag for
exposing model attributes when doing uuid redirects.


  • BLOSSOM-184 Add support for DAM 2.x new package name of

Added features:

  • BLOSSOM-182 Support short-hand syntax for redirecting to the current content
  • BLOSSOM-178 Add exposeModelAttributes property on UuidRedirectViewResolver


We'd like to thank everyone that has invested time in testing and providing feedback. Special thanks goes out to
Dominika and Jean-Charles.

Source cross-reference
Source repository

Version 3.0.2

Small feature release adding support for Spring 3.1 MVC handler methods, callbacks for auto generation of components in
areas and post processing of definitions prior to registration.


  • BLOSSOM-175 MagnoliaMessageSource should have configurable basenames

Added features:

  • BLOSSOM-104 Support for inheriting areas from super class
  • BLOSSOM-111 Add support for auto generation of components in areas
  • BLOSSOM-167 Support Spring MVC 3.1 MVC handler methods
  • BLOSSOM-172 Add post processing callback prior to registration in templates, areas and dialogs
  • BLOSSOM-176 Placeholder for redirecting to the current page

Source cross-reference
Source repository

Version 3.0.1

Small feature release adding support for limiting the number of components in an area and adds access to the Vaadin Item
being used by a dialog.


  • BLOSSOM-152 DialogCreationContext now have methods for accessing the JCR Node directly
  • BLOSSOM-156 The Vaadin Item used by a dialog is now available in DialogCreationContext and methods building dialogs

Added features:

  • BLOSSOM-147 Support for specifying maximum components in an area

We'd like to thank everyone that has invested time in testing and providing feedback. Special thanks goes out to
Francisco J. Giner.

Source cross-reference
Source repository

Version 3.0

Major update for Magnolia 5 style dialogs, compatible with Magnolia 5.1 and later. In version 5 Magnolia has a brand new
user interface and with it comes a new API for dialogs. This version of Blossom is an update for this API and also
contains a few other improvements.

The new user interface is built using Vaadin. In previous versions of Magnolia you would create and configure controls,
now you build an object model that defines how the dialog and its fields should appear and behave. This definition
model is then used to create and configure vaadin components. The fields have better support for validation which is why
@TabValidator and @DialogValidator have been removed in this version.

For composing the dialogs Blossom 3 uses a builder style API that creates a more fluent programming style. A new set of
classes replaces the previous API. These classes include a new TabBuilder and DialogBuilder and provides builders for
each of the built-in fields, making it easier to configure properties on the fields.

A new feature in this release is meta-annotations for component availability. It allows for creating custom annotations
that can then be used on components to categorize them. They can then be used for specifying which components can go
into an area with the @AvailableComponentClasses annotation. All components having a specified annotation will be

Using Springs freemarker macros for forms is now straight forward. When rendering freemarker views Blossom will expose
a RequestContext object which these macros require, it will also expose everything in the model as request attributes.
This feature is enabled by default but can be switched off on the FreemarkerTemplateViewRenderer.

The multipart support that bridges Springs multipart handling to the multipart support in Magnolia has been updated for
API changes made in Spring 3.1.

The groupId changes for this version from info.magnolia to info.magnolia.blossom.


  • BLOSSOM-2 Spring macro helper and the model is now exposed as request attributes in freemarker templates
  • BLOSSOM-89 Multipart resolver now implements methods required in Spring 3.1
  • BLOSSOM-108 UUID redirects are not resolved in pre-execution
  • BLOSSOM-114 BeanFactoryUtils should use SLF4J instead of commons logging
  • BLOSSOM-115 BLOSSOM-121 Update for Magnolia 5.1
  • BLOSSOM-119 Add spring schema for Blossom 3.0
  • BLOSSOM-120 Update bootstrap files for metadata mixins
  • BLOSSOM-127 Change groupId to info.magnolia.blossom
  • BLOSSOM-130 Fix for using the same JSP nested multiple times

Added features:

  • BLOSSOM-106 Extension hooks in TemplateExporter and DialogExporter for post processing definitions
  • BLOSSOM-117 BLOSSOM-135 Add support for Magnolia 5 style dialogs
  • BLOSSOM-131 Meta annotations for component availability
  • BLOSSOM-133 Abstract support class for autowiring of rendering models
  • BLOSSOM-136 Log all registered templates after template export
  • BLOSSOM-142 Provide Node2BeanTransformer with autowiring support

We'd like to thank everyone that has invested time in testing and providing feedback. Special thanks goes out to
Wolfgang Wachsmuth and TLN.

Source cross-reference
Source repository

Version 2.0.6

Adds a short-hand syntax for redirecting to the current content and adds a flag for exposing model attributes when doing uuid redirects.

Added features:

  • BLOSSOM-178 Add exposeModelAttributes property on UuidRedirectViewResolver
  • BLOSSOM-182 Support short-hand syntax for redirecting to the current content

Source cross-reference
Source repository

Version 2.0.5

Small feature release adding support for inheriting areas from super class and a shortcut for redirecting to the current page.


  • BLOSSOM-175 MagnoliaMessageSource should have configurable basenames

Added features:

  • BLOSSOM-104 Support for inheriting areas from super class
  • BLOSSOM-176 Placeholder for redirecting to the current page

Source cross-reference
Source repository

Version 2.0.4

Small feature release adding support for limiting the number of components in an area.

Added features:

  • BLOSSOM-147 Support for specifying maximum components in an area

Source cross-reference
Source repository

Version 2.0.3

Maintenance release for a regression in version 2.0.2.


  • BLOSSOM-159 NPE when opening a dialog

Thanks to Jean-Charles for reporting this.

Source cross-reference
Source repository

Version 2.0.2

Maintenance release fixing a number of reported issues.

Added features:

  • BLOSSOM-112 Template and area definitions should be available for arguments to mvc handler methods


  • BLOSSOM-2 Expose spring macro helper and the model as request attributes in freemarker templates
  • BLOSSOM-96 Exception thrown when trying to export template without required Template annotation should include the class
  • BLOSSOM-101 TemplateDefinitionBuilder#resolveTemplateId throws IllegalStateException (with empty error string) when class is missing Template annotation
  • BLOSSOM-102 Configuration nodes for autodetected templates should be removed when updating from 1.x
  • BLOSSOM-108 UUID redirects are not resolved in pre-execution
  • BLOSSOM-130 Nesting the same JSP + Performance impact
  • BLOSSOM-152 DialogCreationContext now have methods for accessing the JCR Node directly

Thanks to everyone who has reported issues and provided feedback. Special thanks goes out to Tomas Brimor, TLN and Francisco J. Giner.

Source cross-reference
Source repository

Version 2.0.1

Small feature release adding support for finding annotations on proxies and a message on update about migration.


  • BLOSSOM-88 Annotations are not found when using cglib proxies
  • BLOSSOM-94 Added message about migration from 1.2.x

Source cross-reference
Source repository

Version 2.0

Major update for Magnolia 4.5 and its new rendering engine, page editor and templating concepts. With Magnolia 4.5
areas are explicit entities rather than implicit as node collections. The term paragraph is replaced with component.
Components and templates have been streamlined and are internally identical, the only real difference is that they
have different id formats which in turn controls where they're applicable.

@Paragraph has been deprecated and removed. Instead use @Template and set an id of the form <moduleName>:components/*

@ParagraphDescription has been renamed to @TemplateDescription

Templates now have a dialog, use the dialog annotations in the same way as you did for paragraphs.

Ids for templates and components are no longer generated from their @RequestMapping paths. As of this version they need
to be specified on the @Template annotation explicitly.

Paragraphs used to require a dialog even if there was nothing to set. This is no longer the case, a component or
template that doesn't use any of the annotations used to create a dialog will simply not have a dialog. A component is
added to the page immediately without a dialog being shown.

Areas are defined using nested classes (public static class) within a template or another area in which it belongs. They
are normal Spring Web MVC controllers the same as templates and you annotate them with @Area. You can configure which
components are available in them using the @AvailableComponents or @AvailableComponentClasses annotations. Areas have
their own dialog.

An area can inherit components from areas of the same name in the page's parent pages. By default it will only inherit
components marked for inheritance.

The content API, centered on info.magnolia.cms.core.Content, has been deprecated. It's still around and fully backwards
compatible and will be for some time. Instead we favour using the JCR API directly. Therefore in all the places where
Blossom was giving you a Content object you can now instead choose to receive a javax.jcr.Node object. This includes all
the methods you've annotated with blossom annotations as well as your @RequestMapping methods.

No longer necessary to use the ServletContextExposingContextListener as the functionality it provided is now part
of Magnolia itself. The class has been removed, you need to update your web.xml.

The <blossom:configuration> that was previously required in your applicationContext.xml is no longer required and need
to be removed.

Added features:

  • BLOSSOM-65 Templates are dialog factories for their own dialog
  • BLOSSOM-71 @TemplateDescription replaces @ParagraphDescription
  • BLOSSOM-72 @Paragraph is replaced with @Template
  • BLOSSOM-74 Templates are identified with id
  • BLOSSOM-78 Area configuration using nested classes
  • BLOSSOM-82 Areas can have available components set using the classes defining the components
  • BLOSSOM-87 @Available methods can receive the TemplateDefinition for the template


  • BLOSSOM-59 FactoryBeans for beans configured in JCR use JCR API
  • BLOSSOM-61 BlossomWebArgumentResolver supports passing object being rendered as JCR Node instances
  • BLOSSOM-79 ServletContextExposingContextListener is dropped
  • BLOSSOM-81 Empty dialogs are not displayed
  • BLOSSOM-83 Template ids needs to be set explicitly, generation from @RequestMapping is dropped
  • BLOSSOM-84 Template title is set with title field instead of value field

Behind the scenes:

  • BLOSSOM-58 Update for Java 6 and JCR 2.0
  • BLOSSOM-60 upgraded test to JUnit 4
  • BLOSSOM-62 UuidRedirectView and resolver use JCR terminology (workspace instead of repository)
  • BLOSSOM-63 MagnoliaComponentFactoryBean uses Components instead of FactoryUtil
  • BLOSSOM-64 Templates are registered in Magnolia using providers
  • BLOSSOM-67 Update rendering for Magnolia 4.5
  • BLOSSOM-69 TemplateExporter is customizable in beans xml and have full control of the created definition
  • BLOSSOM-70 DialogExporter is customizable in beans xml and have full control the the created definition
  • BLOSSOM-73 Dialog registry is a magnolia component
  • BLOSSOM-75 Dialogs are registered in Magnolia using providers
  • BLOSSOM-76 Update template availability callbacks for Magnolia 4.5

Source cross-reference
Source repository

Version 1.2.4

Small feature release adding support for finding annotations on proxies.


  • BLOSSOM-88 Annotations are not found when using cglib proxies

Source cross-reference
Source repository

Version 1.2.3

Extends the feature set of TabBuilder for adding multi select controls and introduces additional getters. Also makes it
possible to directly add dialog descriptions to the dialog registry. This makes it possible to have new strategies for
dialogs which is required by the new module magnolia-module-blossom-extension-data that adds support for using blossom
dialogs with node types in the data module.

Added features:

  • BLOSSOM-43 Adds TabBuilder.addMultiSelect() addInclude() and addControl()
  • BLOSSOM-50 Adds TabBuilder.getContext()
  • BLOSSOM-53 Adds TabBuilder.getDialog()

Behind the scenes:

  • BLOSSOM-51 Dialog registry accepts dialog descriptions directly and DialogDescriptionBuilder is more open to extension

Source cross-reference
Source repository

Version 1.2.2

Adds an enhancement to BlossomWebArgumentResolver that allows the content objects for both page and paragraph to be
used as argument on annotated controllers. Also fixes two reported bugs.

Added features:

  • BLOSSOM-36 Support both page and paragraph content as arguments on controllers

Bug fixes:

  • BLOSSOM-37 Empty dialog when editing version 0.5 content or using Magnolia before 4.3.2
  • BLOSSOM-40 Model not emptied after rendering of paragraph completes

Source cross-reference
Source repository

Version 1.2.1

Bug fix release. Fixes two issues related to context path and bridging from content rendering into Spring's DispatcherServlet and an issue with context path and uuid redirects.

Bug fixes:

  • BLOSSOM-33 - Simulated forwards should use the webapps context path
  • BLOSSOM-34 - Simulated forward attributes are not visible after an include
  • BLOSSOM-35 - Redirects based on uuid should include contextPath

Source cross-reference
Source repository

Version 1.2

Big enhancements to the feature set and fixes two important bugs. Most notably added support for having beans that are
configured in the repository with support for reloading them transparently when their configuration changes. The feature
builds on an extension to Content2Bean that allows dependency injection, lifecycle events and applying AOP proxies using
the ApplicationContext. As for the ApplicationContext there's a new feature that brings in singletons from Magnolia so
that they can be specified as dependencies in bean definitions or used for autowiring. Also new in this release is a
number of enhancements for working with content in controllers even easier.

Added features:

  • BLOSSOM-14 Make possible to set a SaveHandler for a dialog
  • BLOSSOM-19 Support for DI and AOP in Content2Bean
  • BLOSSOM-20 FactoryBeans for creating beans configured in repository with support for observed reloading
  • BLOSSOM-23 WebArgumentResolver for Content, User, MgnlUser, AggregationState and Context
  • BLOSSOM-24 FactoryBean that exposes magnolia singletons in ApplicationContext
  • BLOSSOM-29 ViewResolver for sending redirects based on uuid
  • BLOSSOM-30 Support for filter and servlet proxies that defer initialization until Magnolia has finished update/install phase
  • BLOSSOM-31 @Available should be overridable in subclasses

Bug fixes:

  • BLOSSOM-16 BlossomDispatcherServlet fails to render when handlerPath is a subset of the requestURI
  • BLOSSOM-18 Multipart support doesn't work with Spring 3

Behind the scenes:

  • BLOSSOM-22 Move BlossomFilter deeper into filter chain to make sure that AggregationState is properly filled in during pre execution
  • BLOSSOM-28 Upgrade to parent pom version 19
  • BLOSSOM-32 Anonymous dialogs for paragraphs should be registered in repository like normal dialogs

Source cross-reference
Source repository

Version 1.1.1

Small feature and bug fix release. The javadoc documentation has been greatly improved and extended. You can now
annotate a method in your templates to control where the template is available. Blossom now also support multipart
requests by exposing Magnolias built in support through the Spring APIs. VirtualURIMappings are now discovered
and automatically exported. There's also support for declaring them using an annotation @VirtualURIMapper. Also, if
you've done customizations to add more argument types to methods for creating and validating dialogs and tabs you'll
be pleased to see that this extension point is now more comprehensible and easy to use.

Added features:

  • BLOSSOM-1 Support for @Available to control where a template can be used
  • BLOSSOM-4 Support for exposing VirtualURIMappings and classes using @VirtualURIMapper
  • BLOSSOM-11 Support for multipart requests, bridges Springs abstraction onto Magnolia multipart processing

Bug fixes:

  • BLOSSOM-5 NPE while detecting dialog factories and encounters abstract bean
  • BLOSSOM-7 ContextLoader is not released correctly on module reload
  • BLOSSOM-12 The autodetected node is created only when needed so it won't be considered as a dialog when its empty
  • BLOSSOM-13 Use of configNode when creating dialogs

Behind the scenes:

  • BLOSSOM-8 Upgrade POM expand javadoc and pass checkstyle tests
  • BLOSSOM-9 Improve package structuring and extract detection of templates, paragraphs and dialogs to separate classes

We'd like to thank everyone that has invested time in testing and providing feedback. Special thanks goes out to Danilo Ghirardelli, Thomas Duffey, Thomas Kalmar and Åke Argéus.

Source cross-reference
Source repository

Version 1.1

Blossom is now maintained and supported by Magnolia International Ltd. Package names and XML
namespace URIs change to reflect this. The Maven artifact is also changed to info.magnolia. Apart from this the release is a minor release with an important bug fix that prevented dialogs from working in Magnolia CMS 4.3.2. Also adds support for initializing Spring within modules, adding radio button controls to dialogs and setting visibility on templates.

Added features:

  • Support for properly getting Spring initialization within module install and startup
  • Added radio button control to TabBuilder
  • Added support for visibility on templates

Bug fixes:

  • Fix for Magnolia CMS 4.3.2, the paragraph edit dialog was broken due to changes in Magnolia CMS
  • TabBuilder.addFile no longer throws RepositoryException
  • Methods in TemplateDescriptionBuilder changed from private to protected
  • Tabs added to dialogs have their name set to match their label

API Changes:

  • Maven artifact groupId is now info.magnolia
  • Package names changed from se.issi.magnolia. to info.magnolia.
  • Spring namespace changed from to

Behind the scenes:

  • Custom paragraph select dialog is removed
  • Blossom pre-execution filter enabled by default on install


Version 1.0

As of version 1.0 Blossom gives you a much bigger feature set and some of the functionality in the previous version has matured. Unfortunately this means that some changes have to be made when upgrading. But don't worry, your content does not have to be touched.

Added features:

  • Support for exposing controllers as Templates
  • Support for creating all types of dialogs with code
  • Localization support for paragraphs, dialogs and templates
  • Rendering of views is performed using the Magnolia CMS render chain, supports both JSP and Freemarker
  • Ordering of dialog tabs is customizable with @TabOrder
  • The locale used by Magnolia can be made visible to Spring using MagnoliaLocaleResolver
  • Magnolia's localization mechanism can be bridged into Spring using MagnoliaMessageSource
  • JSP tag pecid-input is now also available as pecidInput

Behind the scenes:

  • Blossom now exposes controllers are normal paragraphs instead of using a placeholder paragraph
    that delegates rendering to the controller. This is a much cleaner design and allows migration
    of existing content and paragraphs into Blossom.
  • Customization of the paragraph select dialog is no longer necessary.

API Changes:

  • Paragraphs are no longer named after the handlerPath they're mapped to. That is, a controller mapped to /text that was previously referred to in templates as /text is now simply text. This had to be done in order to support migration of existing configured paragraphs into Blossom. Using a forward slash / in a paragraph name was never a good idea in the first place. You don't have to specify a name on your paragraph, it will automatically use the handlerPath stripped from any slashes as its name.
  • @ParagraphTitle is renamed to @Paragraph and moves to se.issi.magnolia.module.blossom.annotation
  • @ParagraphDescription moves to se.issi.magnolia.module.blossom.annotation
  • DialogTabBuilder is renamed to TabBuilder
  • DialogTabBuilder.addText changes to TabBuilder.addEdit
  • Methods in DialogTabBuilder no longer throw RepositoryException
  • Methods in DialogTabBuilder now return the control they create
  • @DialogTabFactory is renamed to @TabFactory and moves to se.issi.magnolia.module.blossom.annotation
  • Ordering of tabs in dialogs are now set using the @TabOrder annotation
  • <blossom:handler-mapping /> is deprecated and removed
  • <blossom:paragraph-registry /> is renamed to <blossom:configuration />
  • Extension hooks in DefaultBlossomParagraphRegistry have new arguments
  • ValidatingParagraph is removed and replaced with @DialogValidator
  • Interface DialogCreator has changed and DefaultDialogCreator changes accordingly.


Version 0.5

Initial release.



Wiki - Blossom examples and articles

Blog - Tobias Mattsson

Tutorial - Spring Framework and Magnolia CMS: Creating Complex Java-based Websites

Conference talk - Integrating Magnolia with Spring Framework using Blossom at Magnolia Conference 2010

Webinar - US Navy Integrates Spring Applications with Flying Colors Thanks to Web CMS