Deploying and Testing Magnolia Module Code, Page 3

The basic module is now ready, and all that's left is to build and deploy it. By convention, Magnolia modules are packaged as JAR archives and deployed to the WEB-INF/lib of the Magnolia CMS authoring and public instances. When Magnolia CMS restarts, it will automatically detect and install the new modules.

The easiest way to compile the new module is with Apache Maven. The included source code archive includes a pom.xmlproject build file that you can use for this purpose. Switch to the project directory, and run the following command at your shell prompt:

shell> mvn tomcat:deploy

You should see something like Figure 4 as Maven builds the project.

Figure 4: Apache Maven JAR Deployment

Assuming no errors, Maven will create a JAR file and place it in the project's example-module/target directory.

To deploy the module to Magnolia CMS, first shut down Magnolia CMS using the Magnolia control script:

shell> magnolia_control.sh stop (on UNIX)
shell> magnolia_control.bat stop (on Windows)

Copy the module JAR file from the project's example-module/target directory to the WEB-INF/lib directory of the Magnolia authoring instance.

If this is the first time you are deploying a Blossom module to Magnolia CMS, you will also need to update the Magnolia authoring instance's web.xml file with an additional context listener, as shown below. Note that this should be placed before Magnolia's own context listener:

info.magnolia.module.blossom.support.ServletContextExposingContextListener

Note: This section assumes that the Magnolia Blossom module and Spring Framework libraries are already present in the WEB-INF/lib directory of the Magnolia authoring instance. If this is not the case, you will have problems deploying and running the module. You can either manually copy these dependencies to the WEB-INF/lib directory of the Magnolia authoring instance, or (recommended) use Maven to manage these dependencies. You can read more about using Maven for dependency management here.

When you're done with all of the above tasks, restart Magnolia CMS:

shell> magnolia_control.sh start (on UNIX)
shell> magnolia_control.bat start (on Windows)

The Magnolia CMS installer should detect your new module(s) and prompt you for an update, as shown in Figure 5.

Figure 5: Magnolia Module Installation

Install the new module, and then log in to the Magnolia CMS AdminCentral. Select the AdminCentral ->Configuration menu and browse through the modules list to the node modules/blossom/paragraphs/autodetected. If all has gone well, Blossom will have auto-detected your new paragraph template and it will appear in the list, as shown in Figure 6.

Figure 6: Template Auto-detection by Blossom

You can now utilize this paragraph template in any page template. Although the module created in the earlier section doesn't include a page template, it's still possible to manually create a page template in Magnolia CMS and use the new paragraph template inside it. To do this, select the AdminCentral -> Configuration menu and browse through the modules list to the node modules/blossom/templating/templates/. Then, create a new template definition as shown in Figure 7.

Figure 7: New Template Definition in Magnolia

After this has been created, create the corresponding template script:

<!--page contentType="text/html;charset=UTF-8" language="java"-->
<!--taglib uri="cms-taglib" prefix="cms"-->
  <h2>${content.title}</h2>
  <div id="content" target=newFrame>
  </div>

Most of this is explained in the templating tutorial, but it's worth pointing out the element, which lists the available paragraphs for this template. Notice that the name specified for the paragraph template matches that specified in the @Paragraph annotation in the controller.

Save this script as $TOMCAT/webapps/magnoliaAuthor/templates/example/example.jsp, and then go back to the Magnolia AdminCentral. You should now be able to use the AdminCentral -> Website -> New Page command to create a new page using this template (see Figure 8).

Figure 8: New Page Creation in Magnolia

Once the page is created, you can preview it by selecting it in the AdminCentral -> Website workspace and using the Open Page... command. Click the New button in the resulting preview window, and Magnolia will present you with a list of available paragraph templates, as shown in Figure 9.

Figure 9: New Paragraph Template Insertion

You can now select the new paragraph template (remember that this is actually a Spring controller). Save your changes, and you should see the template in the preview window (see Figure 10).

Figure 10: Web Form Generated by Paragraph Template

Enter some input into the form and submit it. The input will go back to the Spring controller, which will process your input and return the name of the result template. Figure 11 shows what you should see.

Figure 11: Form Submission Result

Tip: Blossom also supports the use of Spring controllers as page templates. The process is very similar to that for paragraph templates, except that you will annotate the controller with @Template instead of @Paragraph. Look here for an illustrative example.

Conclusion

Of course, this is just the tip of the iceberg. With Spring in play, all manner of interesting things become possible in Magnolia CMS. Still, the examples in this tutorial illustrate how Magnolia's Blossom module makes it easy to integrate advanced features of the Spring Framework with Magnolia's existing templating architecture. This allows developers a great deal of creativity and flexibility when building complex Web sites with custom workflows and non-standard use cases. The use of Spring annotations further simplifies the process, making it possible to reuse existing Spring controllers as Magnolia templates and thereby reduce the overall time, cost and risk of development. Try it out yourself, and see how easy it is!

Code Download

Magnolia-Spring_src

For Further Reading

Set Up the Magnolia CMS for Web Content Creation in Just a Few Clicks (from WebReference)

Publish Web Content Efficiently with Magnolia CMS (from WebReference)

The Magnolia CMS templating tutorial (from documentation.magnolia-cms.com)

About the Author

Vikram Vaswani is a consultant specializing in open-source tools and technologies. He has more than 11 years of experience deploying open-source tools in corporate intranets, high-traffic Web sites, and mission-critical applications. He is a frequent contributor of articles and tutorials to the open source community, and the author of six books on PHP, MySQL and XML technologies.

Page 3 of 3