The first steps with Magnolia development
Ingo Jäger, a CMS specialist at Berlin-based Neofonie, uses the Java-based Magnolia CMS to demonstrate an optimal software stack for developing complex web portals.
When an organisation decides to use a content management system (CMS), and when it has decided on the right system, a developer’s work only really starts. As a developer you need to implement the system and the software stack.
Magnolia from a developer’s perspective
Neofonie implemented a travel portal (spanien.de) and an online portal targeted to preschoolers (toggolino.de) using Magnolia. They used both the free Community Edition and the commercial Enterprise Edition. From a developer’s perspective, Magnolia offers a wide range of flexible use cases thanks to its strong focus on common standards and consistent adoption of established open-source technology. Changing configuration and pieces of functionality is easy. Even switching out whole components is possible with Magnolia.
Training a developer who does not have Magnolia experience is usually a quick and smooth process. You can use REST to access all content and configuration that is stored in the Java Content Repository (JCR). This makes it easy to integrate Magnolia into an ecosystem that already contains multiple components. The REST API also lets developers create and edit content as well as to implement Magnolia commands such as „publish“ or “version“. For example, the REST toolset allows you to import content from external systems into a Magnolia instance, and even gives you the option to publish content remotely. You can read more about this feature in Magnolia documentation.
The system also provides various factory classes and interfaces to implement respective REST client functionality. That way you can integrate external content directly into an editor’s dialog, for example to reference a specific Google news item from a Magnolia article.
If interacting with other system components via REST is not something you can or want to do, Magnolia’s Content Connector interface allows you to access data outside the content repository. The Java classes that make this interface work are easy to integrate into a Magnolia app so that editors can work with external data in the familiar native Magnolia GUI. One use case here would be store digital assets such as images or PDFs in Amazon Web Services instead of in the JCR.
Magnolia makes all source code for the Community Edition publicly available via Git and Nexus. Enterprise Edition source is available to license holders.
Initial setup with Maven
The initial setup of a Magnolia project typically happens with a Maven archetype. Magnolia provides a catalogue of ready-made archetypes. After setting up the Maven project, you find a directory that contains an empty Web application. The actual Magnolia functionality is provided via overlays and dependencies. The basic configuration is initially part of the overlay but you can and should replace it with your own properties.
Just like any other Web application, Magnolia can be deployed into a Tomcat server or any other servlet container.
When you implement custom functionality for your clients or projects, we recommend encapsulating it into a Magnolia module. By that we mean a Magnolia module folder located under a Maven project. Magnolia modules contain a module descriptor (XML) that includes the basic metadata about the module. When you start the Web application, Magnolia detects and loads modules with the help of the module descriptor. See documentation about creating a custom bundle.
In addition to Magnolia properties you also need to configure Jackrabbit when setting up the application. Jackrabbit is the reference implementation of the JCR standard, an open-source software project of the Apache Software Foundation. Jackrabbit is a fully conforming implementation of the JSR-170 and JSR-283 specifications.
Jackrabbit configuration defines the repository home, workspaces, a persistent storage mechanism, versioning, security settings, and a bunch of other things.
When you set up a Magnolia project using a Maven archetype, Jackrabbit is initially configured to use Derby DB as its persistence layer. It is possible and recommended to use other persistence manager classes to manage production data in databases such as MySQL or Oracle or in the file system.
At Neofonie we configured Jackrabbit to use MySQL in the spanien.de and toggolino.de projects. That way we were able to use software products and technologies that match the client’s environment also on the data level and the client can keep using their workflows and processes.
A classic Magnolia installation usually consists of an author and a public instance. Each instance has its own JCR and corresponding configuration. Publishing content always happens from the author instance to the public instance. During the publishing process content is replicated from one JCR repository to another. Magnolia Community Edition only supports publishing to one public instance. However, for failover and load balancing we recommend using at least two public instances in a production environment. Publishing to multiple instances requires a Magnolia Enterprise Edition license. That said, it a Community Edition user has the option to share the JCR between two public instances. Both public instances access the same clustered persistent storage. In other words: two Magnolia instances with the same database (see Step-by-step Magnolia Clustering). We used this method for spanien.de. It was not necessary for toggolino.de because we used the Enterprise Edition which allows publishing to multiple instances.
Blossom Spring Integration Module
The Blossom module turns a Magnolia Web app into a Spring MVC Web app. This offers the developer a variety of options to implement specific business logic and connect Magnolia to external components.
Blossom provides a number of annotations which allow you to implement entire Magnolia templating via a Spring controller. This applies to the implementation of page templates and areas as well as component templates. You can even create dialogs in this way.
Using Blossom involves a few special conditions which depending on the project could turn into disadvantages for the developer:
- Changing a Blossom template requires restarting Magnolia
- Blossom templates are not visible in the Configuration app or anywhere else in the Magnolia user interface. You will always need the source code to be able to understand the configuration and implementation of Blossom-based templates
Magnolia provides a Maven archetype for creating a Blossom module: Getting Started with Blossom.
Magnolia Templating Essentials (MTE)
Magnolia Templating Essentials (MTE) is a minimal set of reusable templates that is quick to learn and requires no prior Magnolia knowledge. It specifically aimed at front-end developers who want to get more done in Magnolia without having to know Java.
According to Magnolia, the MTE is front-end framework agnostic, which means you can integrate it with any modern framework such as Bootstrap or Foundation. This makes Magnolia a good choice for campaign sites and Bootstrap-based sites.
Magnolia content apps
On top of all of these features, Magnolia also has its own app framework. Magnolia apps let you develop custom functionality for creating non-standard content and configuration. Out of the box, Magnolia offers the following apps:
- Content App
- Functional App
- Embedded App
- Small App Layout
Content apps are probably used most. In toggolino.de, we used a content app to create a product catalog where the products are stored and managed in their own JCR workspace.
Existing content apps can usually be copied and adapted easily; it’s often just a matter of configuration and only rarely a case of actually editing Java code. For toggolino.de we copied Magnolia’s own Categories app and adapted it for use in managing teaching categories. All we had to do was edit the app configuration, defining a root node for the category content, and added two fields to a dialog where editors manage categories.
Magnolia Node API
Magnolia offers its own Node API for programmatic development and for manipulating content in the JCR. We used this API a lot in the toggolino.de project to bootstrap configuration programmatically in the version handler class. We also used the Node API to develop an automated importer for TV program data from SUPER RTL, a German television network aimed at children. First, we imported the data from an external source via Spring REST, then mapped it to corresponding Node classes via JAXB, and finally persisted the data to the JCR with the Node API. Different technologies such as Spring REST and JAXB worked together in a fashion typical of Magnolia development. You can use the Scheduler module which is part of the Enterprise Edition to execute such import processes periodically.