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

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

Magnolia Blossom is the Spring integration module for Magnolia. It lets you write reusable paragraphs and templates with a high level of dynamic behavior that editors can compose to create truly interactive web pages. Using the proven application stack of Spring Framework makes it easier to develop integrations with for instance business systems to fetch information you want to present in your pages. If you already know Spring you'll appreciate that Blossom gets you faster up to speed and lets you work in an environment that you're already familiar with.

Key functionality

  • Annotation based API where annotated classes are automatically detected and registered in Magnolia. Simply add @Template to your controller and it will be ready to be used by editors.
  • Exposes controllers as paragraphs and templates, allowing you to use the controller for building a model. Useful if you need to call a web service to get information to present or if you need to read it from a database.
  • Allows you to create dialogs with code instead of configuration. This has many benefits: you can populate the dialog at runtime with options detected at runtime, you get your dialogs out of the repository and into your source control (CVS, SVN, GIT).
  • Dialog validation callbacks for custom validation of input.
  • Execution of a paragraph in front of Magnolia so that it can choose to do a redirect and skip page rendering. Very useful for instance if you have a form that on post should either present an error message or do a redirect.

Versions and compatibility

With Magnolia 5.4 use Blossom 3.1, its documentation is available here
With Magnolia 5.1 to 5.3 use Blossom 3.0, its documentation is available here
With Magnolia 4.5 use Blossom 2.0, i’s documentation is available here
With Magnolia 4.1 to 4.4 use Blossom 1.2

 

Download

Download the Blossom module from Magnolia Store or Nexus repository.

Installing

Blossom is a community module (4.1 and higher). The module is typically not installed and needs to be downloaded. To install see the general  module installation instructions.

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

<dependency>
    <groupId>info.magnolia</groupId>
    <artifactId>magnolia-module-blossom</artifactId>
    <version>1.2.4</version>
</dependency>

Uninstalling

Blossom changes the UI component for editing paragraphs. When you uninstall you need to switch back to the standard component. This is done by setting the node /modules/adminInterface/dialogs/editParagraph/class to info.magnolia.module.admininterface.dialogs.ParagraphEditDialog. See also the general   module uninstalling instructions and advice.

Programming model

This is a brief example of how it's used, these classes are automatically exposed in Magnolia

@Paragraph("Text")
@Controller
public class TextController {

  @TabFactory("Content")
  public void addPropertiesTab(TabBuilder tab) {
      tab.addFckEditor("text", "Text", "").setRequired(true);
  }

  @TabFactory("Margins")
  public void addMarginTab(TabBuilder tab) {}

  @TabValidator("Margins")
  public void validateMargins() {}

  @RequestMapping("/text")
  public String handleRequest() {
      return "text.jsp";
  }
}

@Template("Main")
@Controller
public class MainController {

  @DialogFactory("frontpage-properties")
  public void addDialog(DialogBuilder dialog) {
      TabBuilder tab = dialog.addTab("Properties");
      tab.addEdit("headline", "Headline", "The text to use as a headline");
  }

  @RequestMapping("/main")
  public String handleRequest() {
      return "mainTemplate.ftl";
  }
}

@DialogFactory("main-properties")
public class MainDialogFactory {

  @TabFactory("Properties")
  public void addPropertiesTab(TabBuilder tab) {}

  @DialogValidator
  public void validate(Dialog dialog) {}
}

Getting Started

The fastest way to get a feel for the programming model and how the module works is to run the sample. It's a complete
web application based on Magnolia 4.3 and requires nothing more than a maven installation.

Checkout or export the sources and run using mvn jetty:run-war. When maven has downloaded all the artifacts necessary and started the application point your browser to localhost:8080. Magnolia will be in install mode and display a list of modules it will install. Complete the installation wizard and then login using superuser for both username and password.

= Starting Spring
== Own module (recommended!)
This is the recommended way to start Spring since it will postpone initialization when Magnolia is in install or update mode.

Add this to your web.xml. Make sure you put it before Magnolia's context listener.

<listener>
    <listener-class>info.magnolia.module.blossom.support.ServletContextExposingContextListener</listener-class>
</listener>

Have your module class extend from BlossomModuleSupport and implement your start and stop methods to look something like this:

public class BlossomSampleModule extends BlossomModuleSupport implements ModuleLifecycle {

    public void start(ModuleLifecycleContext moduleLifecycleContext) {
        initRootWebApplicationContext("classpath:/applicationContext.xml");
        initBlossomDispatcherServlet("blossom", "classpath:/blossom-servlet.xml");
    }

    public void stop(ModuleLifecycleContext moduleLifecycleContext) {
        destroyDispatcherServlets();
        closeRootWebApplicationContext();
    }
}

For more details on creating your own module see the documentation of the Module mechanism .

web.xml

You should really consider starting Spring inside your own module (see above). The reason for this is that when Magnolia decides it needs to install or update modules Spring will try to start anyway and will often encounter an error since dependencies on Magnolia will fail when in install/update mode.

Add this to your web.xml. Make sure you put it after Magnolia's context listener.

<listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<servlet>
    <servlet-name>blossom</servlet-name>
    <servlet-class>info.magnolia.module.blossom.render.BlossomDispatcherServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>

Configuration

Add the Blossom configuration to your applicationContext.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:blossom="http://www.magnolia-cms.com/schema/blossom"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.magnolia-cms.com/schema/blossom http://www.magnolia-cms.com/schema/blossom.xsd">

    <blossom:configuration />
</beans>

Add blossom-servlet.xml. This example uses Spring 2.5 component-scan to find the annotated classes. The view resolvers return views for rendering JSPs with Magnolia's JSP renderer. Change the renderers if you're using Freemarker.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <context:annotation-config/>

    <context:component-scan base-package="info.magnolia.module.blossom.sample" use-default-filters="false">
        <context:include-filter type="annotation" expression="info.magnolia.module.blossom.annotation.Paragraph"/>
        <context:include-filter type="annotation" expression="info.magnolia.module.blossom.annotation.Template"/>
        <context:include-filter type="annotation" expression="info.magnolia.module.blossom.annotation.DialogFactory"/>
    </context:component-scan>

    <bean class="org.springframework.web.servlet.mvc.SimpleControllerHandlerAdapter" />
    <bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
        <property name="customArgumentResolver">
            <bean class="info.magnolia.module.blossom.web.BlossomWebArgumentResolver" />
        </property>
    </bean>

    <bean class="info.magnolia.module.blossom.preexecution.BlossomHandlerMapping">
        <property name="targetHandlerMappings">
            <list>
                <bean class="org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping">
                    <property name="useDefaultSuffixPattern" value="false" />
                </bean>
                <bean class="org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping" />
            </list>
        </property>
    </bean>

    <bean class="info.magnolia.module.blossom.view.UuidRedirectViewResolver">
        <property name="order" value="1" />
    </bean>

    <bean class="info.magnolia.module.blossom.view.TemplateViewResolver">
        <property name="order" value="2" />
        <property name="prefix" value="/WEB-INF/views/templates/"/>
        <property name="suffix" value=".jsp"/>
        <property name="viewRenderer">
            <bean class="info.magnolia.module.blossom.view.JspTemplateViewRenderer" />
        </property>
    </bean>

    <bean class="info.magnolia.module.blossom.view.ParagraphViewResolver">
        <property name="order" value="3" />
        <property name="prefix" value="/WEB-INF/views/paragraphs/"/>
        <property name="suffix" value=".jsp"/>
        <property name="viewRenderer">
            <bean class="info.magnolia.module.blossom.view.JspParagraphViewRenderer" />
        </property>
    </bean>
</beans>

Reference


This is the reference documentation for Blossom. The sample code in this section uses Spring 2.5+ annotated controllers but this isn't necessary, you can use Blossom with plain controllers too.

Templates

Exposing a controller as a template is no harder than adding @Template. Consider this example:

@Template("Section Template")
@Controller
public class SectionController {

    @RequestMapping("/section")
    public ModelAndView handleRequest() {
        ...
    }
}

This controller will be exposed in Magnolia and will show up as 'Section Template'.

The name of the template (used internally by Magnolia) will be generated from the path that maps to this controller, in this case it will be section. It's taken from the @RequestMapping annotation and has the leading forward slash / removed. Slashes inside the path will be replaced with underscores _. You can change this behavior by setting the name directly on the class like this:

@Template(value="Section Template", name="my-section-template")

Controlling where a template can be used

Sometimes you want to limit on what pages your template is available for editors to use. This is possible using the @Available annotation. It's used on a method that must return boolean and accept an argument of type Content, this is a page in the website.

    @Available
    public boolean isAvailable(Content websiteNode) {
        // Replace this with logic for your specific use case
        return true;
    }

Paragraphs

Controllers annotated with @Paragraph are exposed in Magnolia in the same way as templates are, consider this example:

@Paragraph("Text and Image")
@ParagraphDescription("Adds a text section with an image")
@Controller
public class TextAndImageController {

    @RequestMapping("/textAndImage")
    public ModelAndView handleRequest() {
        ...
    }
}

This controller will be visible as the Text and Image paragraph. The description set using @ParagraphDescription is shown in the select paragraph dialog.

The name of the paragraph that you specify in templates to have it selectable will be generated from the path that maps to this controller, in this case it will be textAndImage. It's taken from the @RequestMapping annotation and has the leading forward slash / removed. Slashes inside the path will be replaced with underscores _. You can change this behavior by setting the name directly on the class like this:

@Paragraph(value="Text and Image", name="text-and-image")

Dialogs

Blossom has a unique take on dialogs, it lets you create them using code. This has a few neat benefits. If your controller fetches data from say a web service, you could populate your dialog with options retrieved from that web service. For instance, 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. And also, 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 fast.

Dialog factories

Dialog factories create dialogs. They're automatically exposed in Magnolia but you need to configure them as beans in Spring. The easiest way to do this is to use Spring 2.5+ component scan but manual configuration in XML also works.

Have a look at this example:

@DialogFactory("front-page-dialog")
@TabOrder({"Content", "Margins"})
public class FrontPageDialog {

    @TabFactory("Margins")
    public void margins(TabBuilder tab) {
        tab.addStatic("Margins around the side of the front page");
        tab.addEdit("leftMargin", "Left Margin", "Left margin in pixels");
        tab.addEdit("rightMargin", "Right Margin", "Right margin in pixels");
    }

    @TabFactory("Content")
    public void content(TabBuilder tab) {
        tab.addTitle("title", "Title", "The title of this page");
    }
}

A dialog will registered in Magnolia with the name front-page-dialog. It has two tabs, Content and Margins. The order that they appear in has been set using the @TabOrder annotation.

Methods annotated with @TabFactory in superclasses will be called. If you have a lot of dialogs that look the same you can create an abstract base class for them.

Paragraphs create their own dialog

A paragraph 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 paragraph 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 for this paragraph. Like this:

@Paragraph(dialog="my-dialog")

Magnolia can't save a paragraph that has an empty dialog. To get around this add a hidden control that saves some bogus value.

    @TabFactory("Content")
    public void addTab(TabBuilder tab) {
        tab.addStatic("This paragraph requires no configuration");
        tab.addHidden("bogus", "bogus");
    }

Templates can contain dialog factories

It's often the case that you design your template to be used with a few dialogs. Blossom allows you to create these within your template class to keep things in the same place. The concept is similar to dialog factories but here everything is done in a single method.

@Template("product-template")
public class ProductController {

    @DialogFactory("product-dialog")
    public void productDialog(DialogBuilder dialog) {
        TabBuilder settings = dialog.addTab("Settings");
        settings.addEdit("title", "Title", "");
        TabBuilder properties = dialog.addTab("Properties");
        properties.addEdit("headline", "Headline", "");
    }
}

Validating dialog input

As an extra bonus of creating dialogs programmatically Blossom is able to provide you with a callback where you can validate the input that the editor has entered. This is done using the @TabValidator and @DialogValidator annotations. This is possible in both paragraphs and dialog factories.

Validation messages are set using Magnolia's AlertUtil class.

@TabValidator("Content")
public void validateContent(DialogTab tab) {
    DialogEdit title = (DialogEdit) tab.getSub("title");
    if (StringUtils.isEmpty(title.getValue())) {
        AlertUtil.setMessage("You need to enter a title!");
    }
}

@DialogValidator
public void validateDialog(Dialog dialog) {
    ...
}

Adding validators in dialog factories that are nested inside templates.

@DialogFactory("main-properties")
public void createDialog(Dialog dialog, DialogCreationContext context) {
    context.addValidator(new ValidationCallback() {
        public void validate(Dialog dialog) {
            ...
        }
    });
}

Customizing how a dialog is saved

Sometimes its necessary to do post processing before the dialog is saved or to completely replace the built-in behavior with a custom solution. By annotating a method with the @InitSaveHandler annotation the method becomes responsible for creating and initializing a SaveHandler that will be used to save the dialog.

@InitSaveHandler
public SaveHandler initSaveHandler() {
    return new CustomSaveHandler();
}

When the TabBuilder isn't enough

The TabBuilder has methods for adding all the standard controls included in Magnolia CE. When you have a custom control of your own or a control delivered by a third-party module or the enterprise edition this can seem like a serious limitation. Thankfully all you need to create controls on your own is available in DialogCreationContext which you can declare as an argument on your method and have passed to you. It's also possible to extend the dialog creation mechanism in Blossom and replace TabBuilder with a class of your own with methods for adding your custom or third-party controls.

The article Extending the Blossom TabBuilder on the wiki explains how this is done in detail.

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 paragraphs its the content object for the paragraph within the page. If you declare two arguments of type Content the first one will be the content of the page and the second will be the content of the paragraph. Other arguments supported are AggregationState, Context, WebContext, User and MgnlUser.

@RequestMapping("/book")
public String handleRequest(@RequestParam("id") int id, Content page, Content paragraph) {
    …
} 

This is achieved by configuring the BlossomWebArgumentResolver on your AnnotationMethodHandlerAdapter. This is included in the configuration example above.

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. This is done with two view resolvers, one for templates and one for paragraphs. They return views that call into Magnolia. The point being that you usually need to have access to the goodies that Magnolia exposes to you, for instance for accessing the repository.

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.

    return "website:" + content.getUUID();

And this example returns a redirect for a resource in the documents repository.

    return "dms:" + content.getUUID();

The configuration example above shows how to set up the view resolvers.

If you substitute or combine the Blossom view resolvers with your own implementations then you need to keep in mind that the GZip filter included in Magnolia wraps the response object and gives it some odd semantics. It will tell you that the response is not committed even though it's been written to. It will also allow you to do redirects even though the response has been written to. While this might sometimes be a good thing you should know that if you write controllers that exploit this then you depend on the GZip filter and need to have it active. Some 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.

Pre-execution of paragraphs

Pre-execution allows you to write paragraphs 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.

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. For more details see the section below 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 paragraph 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="<paragraph uuid>" />. This tag is also available under the alias <blossom:pecidInput />, this is necessary for use in Freemarker templates.

<%@ taglib uri="blossom-taglib" prefix="blossom" %>
<form action="?" method="POST">
    <blossom:pecid-input />
    <input type="text" name="q" />
    <input type="submit" value="Search" />
</form>

There's also <blossom:pecid var="pecid" /> that will set the paragraph UUID as a variable in this example named pecid. The var attribute is optional, if it's not specified the paragraph UUID is written directly into the page.

<a href="/news/new-website-launched.html?_pecid=<blossom:pecid />"

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've 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. The configuration example above shows how to do this.

You should also note that you have to explicitly declare your HandlerMapping in XML. Spring will supply you with defaults if you don't but Blossom can't get a reference to the defaults and therefore can't take part in the rendering.

Localization

Using @I18nBasename you can set the name of the resource bundle you want to use. It can be used on paragraphs, templates and dialog factories.

If you want Spring to pick up the locale that Magnolia has selected for the current request Blossom provides you with a LocaleResolver that does exactly this.

info.magnolia.module.blossom.context.MagnoliaLocaleResolver

There's also a MessageSource implementation that bridges Magnolia i18n into Spring.

info.magnolia.module.blossom.context.MagnoliaMessageSource

Multipart Requests

Magnolia takes care of handling multipart requests and in order to use them Blossom provides a MultipartResolver implementation. It order to use it add this snippet to your beans xml. In the example above this would be blossom-servlet.xml.

  <bean id="multipartResolver" class="info.magnolia.module.blossom.multipart.BlossomMultipartResolver" />

Virtual URI Mappings

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

Blossom also 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).

@VirtualURIMapper
public class SampleURIMapper {

    public String about(String uri, HttpServletRequest request) {
        if (uri.equals("/about"))
            return "/sections/about";
        return null;
    }

    public String news(String uri, HttpServletRequest request) {
        if (uri.equals("/news"))
            return "forward:/dispatcher/news.do";
        return null;
    }
}

For more details the reference documentation on Virtual URI mapping.

Dependencies on Magnolia Components

Magnolia itself is not based on Spring, instead it uses a container internally that manages its long-lived components. While its simple enough to use that container and get access to components another approach that might be more comfortable for Spring developers is pulling them in as beans in the ApplicationContext where they'll be available for declaring dependencies on them and as candidates for autowiring.

Example that exposes the ModuleManager as a bean with id 'moduleManager'. The id is optional.

<blossom:component id="moduleManager" type="info.magnolia.module.ModuleManager" />

Configuring beans in the repository

The JCR repository is not only used for storing content for web pages. It's also widely used for configuration. One benefit of this is that configuration is easy to change while the application is running. For reading this configuration Magnolia uses a mechanism called Content2Bean. As the name implies it transforms 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 for instance dependencies in the bean that should be autowired by the ApplicationContext. 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 Content2Bean mechanism by default calls a method named 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's 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 service configured in the repository. The service handles discounts.

<blossom:configured-bean id="discountService" path="/modules/book-store-module/beans/discountService" />

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.

<blossom:observed-bean id="discountService" path="/modules/book-store-module/beans/discountService" />

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 Content2Bean see the documentation on Configuration.

Extension points

Many things in Blossom are open for extension. You'll need to consult the source for this. To get you started you need to know that <blossom:configuration /> is short for:

<bean id="blossomConfiguration" class="info.magnolia.module.blossom.BlossomConfiguration" />

This bean has setters for plugging in custom implementations of the internal classes.

Versions and compatibility

  • Blossom has been tested on Magnolia 4.1 and later.
  • Requires Java 5 and has been tested for Java 6.
  • Spring Framework 2.5 and 3.0.

Resources

Wiki - Blossom examples and articles

Blog - Tobias Mattsson

Tutorial - Spring Framework and Magnolia: 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

Version 1.2.4
Javadoc
Source cross-reference
Source repository

Version 1.2.3
Javadoc
Source cross-reference
Source repository

Version 1.2.2
Javadoc
Source cross-reference
Source repository

Version 1.2.1
Javadoc
Source cross-reference
Source repository

Version 1.2
Javadoc
Source cross-reference
Source repository

Version 1.1.1
Javadoc
Source cross-reference
Source repository

Using Spring WebFlow inside Magnolia

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

@Controller
@Paragraph("Booking Flow")
public class BookingFlowController extends FlowController {

    @Override
    @Autowired
    public void setFlowExecutor(FlowExecutor flowExecutor) {
        super.setFlowExecutor(flowExecutor);
    }

    @Override
    @RequestMapping("/booking")
    public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) throws Exception {
        return super.handleRequest(request, response);
    }

    // This is necessary since Magnolia won't add paragraphs with empty dialogs
    @TabFactory("Content")
    public void addTab(TabBuilder tab) {
        tab.addStatic("This paragraph requires no configuration");
        tab.addHidden("bogus", "bogus");
    }
}

There are a few things you need to know though. You have 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.

Examples

Using pre-execution

This is a simple controller that displays a form. The title and description that will appear in the GUI have been set using annotations.

@Controller
@RequestMapping("/search")
@Paragraph("Search form")
@ParagraphDescription("Adds a customizable search form")
public class SearchController {

    @RequestMapping(method = RequestMethod.GET)
    public ModelAndView form() {
        return new ModelAndView("searchForm");
    }

    @RequestMapping(method = RequestMethod.POST)
    public ModelAndView search(@RequestParam("q") String q) {
        if (StringUtils.isBlank(q))
            return new ModelAndView("searchForm", "errorMessage", RepositoryUtils.getLocalNodeData("errorMessage"));
        String searchUrl = RepositoryUtils.getLocalNodeData("searchUrl");
        return new ModelAndView(new RedirectView(searchUrl + q));
    }

    @TabFactory("Settings")
    public void createDialog(TabBuilder builder) {
        builder.addEdit("title", "Title", "");
        builder.addEdit("bodyText", "Text", "");
        builder.addEdit("searchUrl", "Search engine URL", "For instance: http://www.google.com/search?q=");
        builder.addEdit("errorMessage", "Error message", "For instance: You need to enter a query");
    }

    @TabValidator("Settings")
    public void validate(DialogTab dialogTab) {
        DialogEdit title = (DialogEdit) dialogTab.getSub("title");
        if (StringUtils.isEmpty(title.getValue())) {
            AlertUtil.setMessage("You need to enter a title!");
        }
    }
}

And this is the JSP:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ taglib uri="cms-taglib" prefix="cms" %>
<%@ taglib uri="blossom-taglib" prefix="blossom" %>
<cms:editBar />
<h1>${content.title}</h1>
<p><cms:out nodeDataName="bodyText" /></p>
<c:if test="${not empty errorMessage}">
<p style="color:red;">${errorMessage}</p>
</c:if>
<form action="?" method="POST">
    <blossom:pecid-input />
    <input type="text" name="q" />
    <input type="submit" value="Search" />
</form>

Release Notes

Version 1.2.4

Small feature release adding support for finding annotations on proxies.

Improvements:

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

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

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

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

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

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 for your contributions.

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 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 4.3.2, the paragraph edit dialog was broken due to changes in Magnolia
  • 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 http://www.issi.se/schema/blossom to http://www.magnolia-cms.com/schema/blossom

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