Magnolia CMS has a modular architecture. A module is a independent component that performs a particular task or is used to package content and functionality. For an introduction into the module mechanism, see Modules in the Technical Guide

• Configuration items
• Module descriptor elements
• Properties
• Module version handling
• Delta
• Abstract version handler classes
• Task
• Condition
• Dependencies
• Servlets
• Servlet initialization parameters
• Repositories

Configuration items

Magnolia provides standard components including controls, templates, paragraphs, and dialogs. If you create customized implementations of such components you should configure them in your module.

The configured items must be stored directly under the module node in order to be automatically registered by Magnolia. Because Magnolia monitors configured items, any changes in the configuration of registered items will immediately be active. The config node uses Content2Bean to populate all registered module classes as Java Beans with the content of the config node. That is why it is important to put specific configuration details in the config node.

This is a list of available configuration items.

Module descriptor elements

Properties

Properties in the module descriptor can be used to define values for install tasks. You can get the current module descriptor from the InstallContext:

installContext.getCurrentModuleDefinition().getProperty(PROPNAME);

SystemProperty.getProperty(PROPNAME, "default");

Module version handling

The module mechanism facilitates smoother version changes. The idea is that an upgrade or update should be as easy as replacing a module JAR. Magnolia uses the version handler to determine which tasks should be executed. Upon each startup of Magnolia the version handler provides a list of deltas.

Delta

A Delta is a list of Tasks to be executed during a version change. The sample module's version handler provides three Deltas which can be referred to as an example.

More precisely, a Delta can store and apply an additional set of Conditions to be executed only when a version update or revision is deployed. The Tasks of a Delta will only be executed if all specified Conditions are met. We will examine Tasks and Conditions in more detail later in this chapter.

Abstract version handler classes

If you want to create your own version handler you will not have to start from scratch. There are some abstract classes for common cases which can be used. It is good practice to extend one these base classes and implement only the methods you need. There are two abstract version handler classes in the package info.magnolia.module which can be used to create a custom version handler.

If you do not specify a version handler in the module descriptor, the DefaultModuleVersionHandler is used which performs some basic install tasks:

Task

A Task is a lightweight class with only minimal necessary code to augment configuration during module installation. The important method in the Task interface is:

void execute(InstallContext installContext) throws TaskExecutionException;

There is already a set of predefined and abstract Tasks available in the package info.magnolia.module.delta which can be used. Here are some of the most useful: AbstractTask, AbstractRepositoryTask, AbstractConditionalRepositoryTask, AllChildrenNodesOperation, AllModulesNodeOperation.

Also interesting are delegate Tasks:

ArrayDelegateTask, ConditionalDelegateTask, PropertyExistsDelegateTask, PropertyValueDelegateTask.

For the complete list of Tasks, please consult the javadoc.

It is customary for modules to expose some tasks that can be re-used by other modules when needed, such as RegisterNodeTypeTask. The API is designed so that it should be easy for you to write your own specific Task implementations.

Condition

Conditions are checked prior to the installation or update of a module. They check for system configuration which can't be automatically updated, like configuration, dependencies, etc. Modules register their Conditions like their Tasks, for each successive version. Only if all Conditions in Delta evaluate positively will the Tasks of the Delta be executed. The most important method in the Condition interface is:

boolean check(InstallContext installContext);

Dependencies

You can define runtime or install time dependencies (not build dependencies). If you define a dependency on a module, then this module will be installed and started before your module. A dependency can be optional which means that if an optional module is not present, installation will proceed, if the optional module is present, this module will be installed first. The dependencies could look like this:

<dependencies>
    <dependency>
      <name>core</name>
      <version>3.6.0/*</version>
    </dependency>
    <!--  in case cache module is present, 
    make sure we install after so we can add a bypass -->
    <dependency>
      <name>cache</name>
      <version>3.6.0/*</version>
      <optional>true</optional>
    </dependency>
  </dependencies>

Taking * for the from version means "to version or lower"

Taking * for the to version means "from version or higher"

Some examples:

Servlets

Instead of defining servlets in web.xml, servlets can be defined in the module descriptor using the same values as in web.xml. The DMS module for example registers a servlet to deliver the documents:

  <servlets>
    <servlet>
      <name>DMSDownloadServlet</name>
      <class>info.magnolia.module.dms.DMSDownloadServlet</class>
      <comment>DMS download servlet</comment>
      <mappings>
        <mapping>/dms/*</mapping>
        <mapping>/dms-static/*</mapping>
      </mappings>
    </servlet>
  </servlets>

Servlet initialization parameters

You can specify initialization parameters for servlets in the module descriptor file. These parameters are the equivalent of servlet initialization parameters in a web.xml file. Use the following syntax in the descriptor:

<params>
  <param>
    <name>name</name>
    <value>value</value>
  </param>
</params>

Examples:

• fkcEditor.xml
• webdav.xml
• opensocial-container.xml

Repositories

  <repositories>
    <repository>
      <name>magnolia</name>
      <workspaces>
        <workspace>data</workspace>
      </workspaces>
      <nodeTypeFile>/mgnl-nodetypes/magnolia-module-data-nodetypes.xml</nodeTypeFile>
    </repository>
  </repositories>