Blossom module

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.

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

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

It is also possible to keep the existing dialog factories, using 5 UI compatibility definitions, through UiConfig, TabBuilder and so on. In this case, the definitions are converted on the fly to the equivalent 6 UI dialogs. The conversion is done using the Field converters.

While the Magnolia 6 UI framework does not have configurable form-dialog presenters, nor Vaadin 7 items, the 5 UI (compatibility) Pages app may still be used for cases relying on them.

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.

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.

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.

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 AggregationState, Context, WebContext, User and MgnlUser:

To do this, configure the BlossomHandlerMethodArgumentResolver on your RequestMappingHandlerAdapter.

In addition to the content you can access a range of objects about the current rendering context by adding them as arguments to your @RequestMapping annotated methods.

On templates, areas and components you can declare parameters that can then be accessed in the view using the def.parameters.<parameter-name> notation.

Example:

To access the example parameter in a freemarker view use:

View rendering with Blossom is performed by Spring. Blossom comes with support for using the Magnolia rendering chain. As a result you’ll have access to all the objects that Magnolia provides to template scripts.

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 running in debug mode. This makes developing dialogs extremely fast.

Since version 3.6.0, @DialogFactories and @TabFactories can inject Spring-managed beans, as well as parameters resolved through Spring HandlerMethodArgumentResolvers (including custom resolvers).

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 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/cms/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.

When you have multiple forms on the same page it can be helpful to distinguish which one is supposed to handle a POST request by testing in a controller if it is being pre-executed.

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

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.

You can also leave labels and titles empty to have Magnolia resolve them automatically by generating a key based on the dialog’s name, the tab’s name, and the field’s name. However by default Blossom will use the value given in @TabFactory both for name and label of the tab. In order to leave the label empty so automatic i18n takes effect you need to set a property in your module descriptor.

In the site definition you can define a template prototype which is a template that other templates inherit from. Things configured on the prototype such as areas are copied onto other templates.

To use this feature with Blossom you need to use a special view renderer. Blossom provides a FactoryBean for creating this renderer, SiteAwareFreemarkerTemplateViewRendererFactoryBean.

The Blossom sample has example configuration for this renderer and the getting started guide uses a Maven archetype that generates this configuration for you.

For more details see the documentation on the site definition.

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.

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.

Magnolia 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':

(Note the id is optional). For more details on Magnolia Components see the documentation on Configuration.

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:

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.

For more details on Node2Bean see the documentation on Configuration.

When using standard Magnolia templates with RenderingModel classes do their backing logic you can get access to beans managed by Spring through autowiring. Blossom provides an abstract base class for this called AbstractAutowiredRenderingModel. It will do autowiring on itself using the root web application context. Note that Magnolia will still create the RenderingModel and since it supports the @Inject annotation you should use @Autowired for the dependencies you want to from Spring.

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.

The <mvc:annotation-driven/> tag is essentially a macro. It adds a number of beans, such as message converters, handler adapters and so on. They’re all configured with reasonable defaults that suits the majority of users. That is, until you actually need something that differs from the defaults. Then you need to remove it and explicitly configure instead.

In order for Blossom to work it customizes some of the same beans that <mvc:annotation-driven/> adds. Therefor some things will break when you add <mvc:annotation-driven/>. One thing that does break is pre-execution. In order for it to work all handler adapters need to be configured within a BlossomHandlerMapping bean.

A common reason for adding <mvc:annotation-driven/> is bean validation of submitted forms since it adds configuration for this by default. When using Blossom you need to set up configuration for bean validation explicitly. If you’ve used the archetypes to create your module this was done for you. Otherwise refer to this snippet that shows how its done:

Controllers used for rendering content are not accessible for requests coming in to the servlet container. Requests that come in are handled my Magnolia and mapped to content that is only later rendered by these controllers. The BlossomDispatcherServlet that manages these controllers are started in your module class and the servlet container has no knowledge of this servlet. Since these controllers are non meaningful without content there’s no reason to have them directly accessible.

Controllers that should be accessible directly and are not used to render content need to be managed by a different DispatcherServlet.

There’s two ways to add a DispatcherServlet in a Magnolia project. You either simply add one to web.xml or you add to your module descriptor.

Adding it to the module descriptor is the better choice because then its started after your module has started and it will become a child of the root web application context and can access all beans within it. You also won’t need to update web.xml which makes module install easier and upgrades of Magnolia easier.

The module descriptor is your /src/main/resources/META-INF/magnolia/<module name>.xml file.

Here’s an example of what that looks like:

Magnolia installs the servlet when the module is installed so after you’ve added it you need to reinstall your module. When it’s installed you can see it in the configuration app at /server/filters/servlets/dispatcher.

In the example above the DispatcherServlet will get all requests with a path starting with /ajax/ and it uses a configuration file/src/main/resources/ajax-servlet.xml.

You’ll want to make sure that ajax-servlet.xml has only the controllers that should be accessible from the outside and not those used for rendering content. Do this by organizing them in different packages and use component scan to find the right ones.

Here’s what a simple ajax-servlet.xml would look like:

It will component scan and find the controller below which becomes accessible at /ajax/hello, note that the /ajax part is not specified in the controller.

This is a simple controller that displays a form:

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

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.