Blossom - Fully working example

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

mvn archetype:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public/

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "module.dtd" >
<module>
	<name>${project.artifactId}</name>
	<displayName>${project.name}</displayName>
	<description>${project.description}</description>
	<class>com.hyro.magnolia.blossom.core.ModuleCore</class>
	<versionHandler>com.hyro.magnolia.blossom.core.ModuleVersionHandler</versionHandler>
	<version>${project.version}</version>

	<dependencies>
		<dependency>
			<name>core</name>
			<version>4.1/*</version>
		</dependency>
	</dependencies>

</module>

package com.hyro.magnolia.blossom.core;

import info.magnolia.module.ModuleLifecycle;
import info.magnolia.module.ModuleLifecycleContext;
import info.magnolia.module.blossom.module.BlossomModuleSupport;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * Core class of the Magnolia and Blossom Module.<br/>
 * Starts the Spring Context using Blossom.
 *
 * @author bruno.chauvet
 *
 */
public class ModuleCore extends BlossomModuleSupport implements ModuleLifecycle {
    private static final Logger LOGGER = LoggerFactory.getLogger(ModuleCore.class);
    private static ModuleCore instance;

    /**
     * Initialise the instance variable
     */
    public ModuleCore() {
        ModuleCore.instance = this;
    }

    /**
     * Return the singleton instance
     *
     * @return
     */
    public static ModuleCore getInstance() {
        return ModuleCore.instance;
    }

    /**
     * Starts the Spring/Blossom context.
     */
    public void start(ModuleLifecycleContext moduleLifecycleContext) {
        ModuleCore.LOGGER.info(this.getClass().getSimpleName() + " is starting");
        super.initRootWebApplicationContext("classpath:/applicationContext.xml");
        super.initBlossomDispatcherServlet("blossom", "classpath:/blossom-servlet.xml");
    }

    /**
     * Stops the Spring/Blossom context.
     */
    public void stop(ModuleLifecycleContext moduleLifecycleContext) {
        ModuleCore.LOGGER.info(this.getClass().getSimpleName() + " is stopping");
        super.destroyDispatcherServlets();
        super.closeRootWebApplicationContext();
    }
}

package com.hyro.magnolia.blossom.core;

import info.magnolia.module.DefaultModuleVersionHandler;
import info.magnolia.module.InstallContext;
import info.magnolia.module.delta.DeltaBuilder;
import info.magnolia.module.delta.ModuleBootstrapTask;
import info.magnolia.module.delta.ModuleFilesExtraction;
import info.magnolia.module.delta.Task;

import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * This class instructs Magnolia on what to do when this module is installed or
 * updated.
 *
 * @author bruno.chauvet
 *
 */
public class ModuleVersionHandler extends DefaultModuleVersionHandler {
    private static final Logger LOGGER = LoggerFactory.getLogger(ModuleVersionHandler.class);
    private static final String PROPERTY_FILE = "application.properties";

    /**
     * ModuleVersionHandler Constructor.
     *
     * Register any tasks in here that need to happen as part of an update. All
     * though the constructor here will always be invoked, it will only ever
     * have an effect for updates (not new installs) because the DeltaBuilder is
     * adding "update" tasks. By default new installs are setup correctly
     * through inherited behaviour. However, if you need to perform additional
     * non default tasks as part of a new install the way this needs to be done
     * is by overriding the getExtraInstallTasks() method and adding additional
     * non-default tasks in here.
     *
     * @see <a
     *      href="[WIKI|Handling module versions]">
     *          http://wiki.magnolia-cms.com/display/WIKI/Handling+module+versions
     *      </a>
     *      for more info on module versioning
     *
     */
    public ModuleVersionHandler() {
        // Get the module version from the properties
        InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(PROPERTY_FILE);
        Properties properties = new Properties();
        try {
            properties.load(is);
        } catch (IOException e) {
            ModuleVersionHandler.LOGGER.error("Cannot load property file: " + PROPERTY_FILE, e);
        }

        // Register the module using version specified in the properties.
        super.register(DeltaBuilder.update(properties.getProperty("Application.version"), "Common tasks").addTasks(
                getCommonTasks()));
    }

    /**
     * Overwrites the list of tasks to perform during module installation.
     */
    @Override
    protected List<Task> getExtraInstallTasks(InstallContext installContext) {
        return this.getCommonTasks();
    }

    /**
     * Return the common task for every module update.
     *
     * @return
     */
    private List<Task> getCommonTasks() {
        final List<Task> commonTasks = new ArrayList<Task>();

        // Installs all files from
        // /src/main/resources/mgnl-bootstrap
        commonTasks.add(new ModuleBootstrapTask());

        // Extracts all files from
        // /src/main/resources/mgnl-files
        commonTasks.add(new ModuleFilesExtraction());

        return commonTasks;
    }
}

Application.name=${project.artifactId}
Application.version=${project.version}

<?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-2.5.xsd
		http://www.magnolia-cms.com/schema/blossom http://www.magnolia-cms.com/schema/blossom-1.1.xsd">

	<blossom:configuration />
</beans>

<?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-2.5.xsd
		http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd">

	<context:annotation-config />

	<context:component-scan base-package="com.hyro.magnolia.blossom.controller" />

	<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.TemplateViewResolver">
		<property name="prefix" value="/templates/${project.artifactId}/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="prefix" value="/templates/${project.artifactId}/paragraphs/" />
		<property name="suffix" value=".jsp" />
		<property name="viewRenderer">
			<bean class="info.magnolia.module.blossom.view.JspParagraphViewRenderer" />
		</property>
	</bean>
</beans>

package com.hyro.magnolia.blossom.controller.template;

import info.magnolia.module.blossom.annotation.DialogFactory;
import info.magnolia.module.blossom.annotation.Template;
import info.magnolia.module.blossom.dialog.DialogBuilder;
import info.magnolia.module.blossom.dialog.TabBuilder;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

/**
 * Controller defining the Main Template.
 *
 * @author bruno.chauvet
 *
 */
@Template(name = "main-template", value = "Main Template", description = "Main Template example with Blossom", visible = true)
@Controller
public class MainTemplate {
    /**
     * Process the requests on URL /mainTemplate
     *
     * @return
     */
    @RequestMapping("/mainTemplate")
    public ModelAndView homeTemplate() {
        return new ModelAndView();
    }

    /**
     * Dialog factory associated to the Main page settings.
     *
     * @param dialog
     */
    @DialogFactory("main-dialog")
    public void homeDialog(DialogBuilder dialog) {
        TabBuilder settings = dialog.addTab("Main page settings");
        settings.addEdit("title", "Title", "The HTML page title");
        settings.addEdit("metaDescription", "Meta Description", "HTML Meta Description of the web site");
        settings.addEdit("metaKeywords", "Meta Keywords", "HTML Meta Keywords of the web site");
    }
}

package com.hyro.magnolia.blossom.controller.paragraph;
import info.magnolia.module.blossom.annotation.DialogFactory;
import info.magnolia.module.blossom.annotation.Paragraph;
import info.magnolia.module.blossom.annotation.ParagraphDescription;
import info.magnolia.module.blossom.annotation.TabFactory;
import info.magnolia.module.blossom.dialog.TabBuilder;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

/**
 * Controller defining the Header paragraph and dialog.
 *
 * @author bruno.chauvet
 *
 */
@Paragraph(name = "headerParagraph", value = "Header Paragraph", dialog = "header-dialog")
@ParagraphDescription("Header Paragraph")
@DialogFactory("header-dialog")
@Controller
public class HeaderParagraph {
    /**
     * Process the requests on URL /headerParagraph
     *
     * @return
     */
    @RequestMapping("/headerParagraph")
    public ModelAndView handleRequest() {
        return new ModelAndView();
    }

    /**
     * Tabs of the Header Paragraph.
     *
     * @param tab
     */
    @TabFactory("Header")
    public void content(TabBuilder tab) {
        tab.addStatic("Header paragraph");
        // Logo image
        tab.addFile("logo", "Logo", "Logo Image (about 120 x 100 px)");
        // Header text
        tab.addEdit("text", "Header Text", "Header Text (about 60 characters)");
    }
}

package com.hyro.magnolia.blossom.controller.paragraph;

import info.magnolia.cms.gui.dialog.DialogEdit;
import info.magnolia.cms.gui.dialog.DialogTab;
import info.magnolia.cms.util.AlertUtil;
import info.magnolia.module.blossom.annotation.DialogFactory;
import info.magnolia.module.blossom.annotation.Paragraph;
import info.magnolia.module.blossom.annotation.ParagraphDescription;
import info.magnolia.module.blossom.annotation.TabFactory;
import info.magnolia.module.blossom.annotation.TabOrder;
import info.magnolia.module.blossom.annotation.TabValidator;
import info.magnolia.module.blossom.dialog.TabBuilder;

import org.apache.commons.lang.StringUtils;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

/**
 * Controller defining a Simple Paragraph.
 *
 * @author bruno.chauvet
 *
 */
@Paragraph(name = "simpleParagraph", value = "Simple Paragraph", dialog = "simple-dialog")
@ParagraphDescription("Simple Paragraph with title, text, description, image and link")
@DialogFactory("simple-dialog")
@TabOrder({ "Content", "Description" })
@Controller
public class SimpleParagraph {
    /**
     * Process the requests on URL /simpleParagraph
     *
     * @return
     */
    @RequestMapping("/simpleParagraph")
    public ModelAndView handleRequest() {
        return new ModelAndView();
    }

    /**
     * First Dialog Tab.
     *
     * @param tab
     */
    @TabFactory("Content")
    public void content(TabBuilder tab) {
        tab.addStatic("Title, image and link of the paragraph");
        tab.addEdit("title", "Title", "");
        tab.addFile("image", "Image", "Image 100 x 70 px");
        tab.addEdit("linkText", "Link Text", "");
        tab.addLink("link", "Link", "");
    }

    /**
     * Second Dialog Tab.
     *
     * @param tab
     */
    @TabFactory("Description")
    public void description(TabBuilder tab) {
        tab.addStatic("Description of the paragraph");
        tab.addFckEditor("description", "Description", "Rich text editor");
    }

    /**
     * First Tab Validator.
     *
     * @param dialogTab
     */
    @TabValidator("Content")
    public void validate(DialogTab dialogTab) {
        DialogEdit title = (DialogEdit) dialogTab.getSub("title");
        if (StringUtils.isEmpty(title.getValue())) {
            AlertUtil.setMessage("You need to enter a title !");
        }
    }
}

package com.hyro.magnolia.blossom.controller.paragraph;

import info.magnolia.cms.gui.dialog.DialogEdit;
import info.magnolia.cms.gui.dialog.DialogTab;
import info.magnolia.cms.util.AlertUtil;
import info.magnolia.module.blossom.annotation.DialogFactory;
import info.magnolia.module.blossom.annotation.Paragraph;
import info.magnolia.module.blossom.annotation.ParagraphDescription;
import info.magnolia.module.blossom.annotation.TabFactory;
import info.magnolia.module.blossom.annotation.TabValidator;
import info.magnolia.module.blossom.dialog.TabBuilder;

import org.apache.commons.lang.StringUtils;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

/**
 * Controller defining a Nested Paragraph.
 *
 * @author bruno.chauvet
 *
 */
@Paragraph(name = "nestedParagraph", value = "Nested Paragraph", dialog = "nested-dialog")
@ParagraphDescription("Nested Paragraph with a title and a list of links")
@DialogFactory("nested-dialog")
@Controller
public class NestedParagraph {
    @RequestMapping("/nestedParagraph")
    public ModelAndView handleRequest() {
        return new ModelAndView();
    }

    @TabFactory("Content")
    public void content(TabBuilder tab) {
        tab.addStatic("Title, Title of the paragraph");
        tab.addEdit("title", "Title", "Main title");
    }

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

package com.hyro.magnolia.blossom.controller.paragraph;

import info.magnolia.cms.gui.dialog.DialogEdit;
import info.magnolia.cms.gui.dialog.DialogTab;
import info.magnolia.cms.util.AlertUtil;
import info.magnolia.module.blossom.annotation.DialogFactory;
import info.magnolia.module.blossom.annotation.Paragraph;
import info.magnolia.module.blossom.annotation.ParagraphDescription;
import info.magnolia.module.blossom.annotation.TabFactory;
import info.magnolia.module.blossom.annotation.TabValidator;
import info.magnolia.module.blossom.dialog.TabBuilder;

import org.apache.commons.lang.StringUtils;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

/**
 * Controller defining a Nested SubParagraph.
 *
 * @author bruno.chauvet
 *
 */
@Paragraph(name = "nestedSubParagraph", value = "Nested SubParagraph", dialog = "nested-sub-dialog")
@ParagraphDescription("Nested SubParagraph with title and links")
@DialogFactory("nested-sub-dialog")
@Controller
public class NestedSubParagraph {
    @RequestMapping("/nestedSubParagraph")
    public ModelAndView handleRequest() {
        return new ModelAndView();
    }

    @TabFactory("Content")
    public void content(TabBuilder tab) {
        tab.addStatic("Title, Title of the paragraph");
        tab.addEdit("text", "Text", "Text");
        tab.addLink("link", "Link", "Link");
    }

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

<div class="nested">
<h2>${content.title}</h2>

<!-- Counter to display subparagraphs on two columns -->
<c:set var="index" value="1" scope="request" />

<ul class="nested">
	<cms:contentNodeIterator
		contentNodeCollectionName="NestedSubParagraphs">
		<cms:includeTemplate />
	</cms:contentNodeIterator>
</ul>

<cms:newBar contentNodeCollectionName="NestedSubParagraphs"
	paragraph="nestedSubParagraph" newLabel="New Link" />

<cms:editBar editLabel="Edit Paragraph" />
</div>

<!-- Start a new list when half of the subparagraphs have been displayed -->
<c:if test="${index > (size/2)}">
	<c:set var="index" value="1" scope="request" />
	</ul>
	<ul class="nested">
</c:if>

<li><a href="${content.link}">${content.text}</a> <cms:editBar
	editLabel="Edit Link" /></li>

<c:set var="index" value="${index + 1}" scope="request" />