Magnolia CMS is configured using properties, components, observation and a mechanism known as Content2Bean.

• Properties
• Multiple configurations, one Web application archive
• Components
• Content2Bean
• Where is Content2Bean used?
• Extending configuration
• Observation

Properties

Magnolia CMS is primarily configured using properties. Properties come from multiple different sources, processed in the following order:

Sources processed earlier may be overridden by sources processed later. The distribution of properties into several sources and the processing order allow flexible customization.

Some key properties set in the default magnolia.properties file:

# Repository configuration
magnolia.repositories.config = WEB-INF/config/default/repositories.xml
magnolia.repositories.home = ${magnolia.app.rootdir}/repositories
magnolia.repositories.jackrabbit.config = WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml

# Defining the instance as author instance
# Only used for the initial installation.
# Afterwards configuration in the config repository is used.
# The value is saved in /server/admin
magnolia.bootstrap.authorInstance=true
# Switch to false to enhance the performance of Javascript generation
magnolia.develop=false
# Set to true if bootstrapping/update should be performed automatically
magnolia.update.auto=false

Multiple configurations, one Web application archive

You can bundle different configuration sets in the same webapp. They are automatically applied depending on the server name or webapp name.

WEB-INF/config/default/magnolia.properties
WEB-INF/config/${webapp}/magnolia.properties
WEB-INF/config/${servername}/magnolia.properties
WEB-INF/config/${servername}/${webapp}/ magnolia.properties

Default properties are common regardless of the server name or webapp name. Webapp specific properties are installed only if the webapp name matches. Correspondingly, server specific properties are only installed if the server name matches.

For example, Magnolia CMS ships with two webapps by default: magnoliaAuthor and magnoliaPublic. The magnoliaPublic app becomes a public instance because of the way it is named.

An example of server specific configuration is setting a different persistence manager per environment. On a development instance the persistence manager could be the default embedded Derby database but on a production instance you would want to use production-scale persistent storage such as a MySQL database. If you use MySQL, choose the InnoDB storage engine. MyISAM engine is not supported by Magnolia.

See WAR file with multiple configurations for more on this topic.

Components

Magnolia CMS uses components provided by a Components service. Magnolia properties can be used to define which concrete class should be used to instantiate a certain component. The property key is the interface or class name and value is the concrete class or a path which maps to the config workspace. If the value is a path then the Content2Bean mechanism is used to build the instance.

Example configuration:

# Map to a path in the config workspace
info.magnolia.cms.i18n.I18nContentSupport = /server/i18n/content
# Concrete class implementing the interface
info.magnolia.module.ModuleManager = info.magnolia.module.ModuleManagerImpl

Some default classes are defined in file mgnl-beans.properties provided by the core JAR. The values can be overwritten and defined in the module descriptor or properties configuration files.

Examples of components:

• SecurityManager. Used to read users, groups and roles.
• TemplateManager. Provides a template definition used in rendering.
• ModuleRegistry. Holds instances and definitions of modules.

I18nContentSupport i18n = Components.getSingleton(I18nContentSupport.class);

Content2Bean

Most of Magnolia CMS configuration is stored in the config workspace. A mechanism known as Content2Bean is used to transfer the configuration from the workspace into a Java object. Content2Bean populates a JavaBean with the content of a repository node, including sub nodes.

With Content2Bean's "setter" and "getter" methods you can populate configuration collections and maps. The methods can handle simple data types (String, int, float, double, Boolean), custom data types, collections and maps with key-value pairs.

The class used to instantiate an object through the Content2Bean mechanism is determined through reflection or by explicitly referencing a class in the class node data. By referencing a specific class you can override Magnolia CMS default configuration and implement your own caching behavior, security mechanism and so on.

Numbered items:

1. config is the entry point of the transformation. In the module descriptor we define that SampleConfig class is used. text and number properties will be set.
2. sub is a sub bean. The class is determined using reflection if not explicitly defined.
3. items is a collection. The corresponding add method is used to determine the class and populate the collection if existing.
4. item2 is a special item. It has its own class and additional properties.
5. parameters is a collection of key-value pairs.

Where is Content2Bean used?

Module instances. A module's configuration data is transferred into a Bean from /modules/moduleName/config. The Bean class to build is defined in the module descriptor XML file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "module.dtd">
  <module>
    <name>samples</name>
    <displayName>Magnolia Samples Module </displayName>
    <class>
      info.magnolia.module.samples.SamplesModule 
    </class>

Components. If a path in the config workspace is given rather than a concrete class name, then Content2Bean is used to build the component instance.

# Map to a path in the config workspace
info.magnolia.cms.i18n.I18nContentSupport = /server/i18n/content

Additional items such as paragraphs, templates and virtual URI mappings configured at module level.

Extending configuration

One configuration can extend another. Extending is done by defining an extends data node and setting its value to the source configuration you want to inherit. The target configuration inherits everything from the source and adds its own exceptions. This can save time and effort as you only need to define exceptions explicitly. The mechanism is only available in the config repository.

In the example below, the demo-project site definition extends the default site definition. It inherits all configuration from the default and adds its own domains, internationalization and URI-to-repository mappings. The extends property can point to the source configuration with an absolute or relative path.

Extending is additive by default, which means configuration specified at the extending level is added to the inherited configuration. Setting the extends property to override changes this behavior. An override allows the extending node to completely remove the inherited content and replace it with its own content entries.

In the example below, the demo-project site definition supports two locales, en (English) and de (German), whereas site demo-project-fr is targeted to French speakers only. The French site extends demo-project. It inherits all configuration except the locales. An override under the locales content node removes en and de. Only the French locale fr defined at this level is applied. This means authors can enter only French content on the French site.

Observation

Observation is a Java Content Repository feature that allows applications to register interest in events that change a workspace and then monitor and respond to those events. The observation mechanism dispatches events when a persistent change is made to the workspace. Magnolia CMS uses observation heavily. For instance, observation is used to reload module configurations and to reload all objects.