Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

Magnolia has a modular architecture. A module can perform a task, package content, or provide specialized functionality. Modules can be project specific or they can be reused across different projects. You should use the module mechanism to package and deploy your own site's configuration and functionality.

Terminology

In Magnolia documentation, the terms module and project module always refer to a Magnolia module. Magnolia modules contain files which are specific to Magnolia.

Maven also uses the term module but it means something different. Some of the modules which build the Magnolia software are indeed Maven modules. This is the case with submodules of the magnolia-ui-project such as magnolia-ui-api and magnolia-ui-form. When Maven module is meant, we write Maven module.

Best practice

When you are creating a website project, you should have one module for templates, another module for content, a third for a theme and so on. While the project handles dependency management for all modules defined in the project, each module contains the files and logic for the functionality of that specific module.

Overview and characteristics

Many modules are independent and pluggable, meaning you can add and remove them at will. For example, if you don't need the Workflow module and would rather publish pages to the public instance directly, you can remove the module from Magnolia. A module consists of a set of components packaged in a JAR file. Deploying a module is a matter of copying the JAR file into the WEB-INF/lib folder and restarting the instance. Magnolia update wizard recognizes the JAR and installs its contents.

A Magnolia module:

Module configuration items

Magnolia provides standard module configuration items such as fields, template types (pages, areas, components), and dialogs. You need to configure any customized implementations in your module. Module configuration uses the Node2Bean mechanism to populate all registered module classes as Java Beans with the content of the configuration node. Because Magnolia monitors configured items, any changes in the configuration of registered items will immediately be active.

Here's the configuration for the RSS Aggregator module:

Node nameValue
 modules

 rssaggregator


 apps


 fieldTypes


 dialogs


 config


 commands


 virtualURIMapping


 templates


Folders:

Configuration item

Purpose

Details and examples

appsDefines the app descriptor to use.An app descriptor is a group of configuration nodes that describe the app. You can define a proper app descriptor to meet your special needs.

commands

Define commands to use with the Magnolia command management.

An example of a command is send mail which is part of the Mail module. Commands can perform duties within the system or connect to external resources.

config

Module-specific configuration which will be available via the module class (see below).

Config contains parameters and data for your module.

dialogs

Define a configured dialog.

Dialog to edit the content of sample text & image of component.

fieldTypes

Define your own field type.

Magnolia provides a number of field types to meet your common needs. See Fields for the field type list and their details.

messageViews

Defines the display and allowed operations of a message.

There are three message types that catch a user's attention to a greater of lesser degree. To configure the display of the message and operations that editors can do, see Message views.

renderers

Defines a new render type.

Magnolia ships with JSP and FreeMarker template renderers. You can also integrate logic before rendering a page, area or component by using a custom renderer or injecting your implementation of the standard renderers. It is possible to create a custom renderer for another templating language, e.g. Velocity.

templates

Defines the template definitions. Templates can be pages or components. They can use FreeMarker, JSP or a custom templating language.

For example, stkNews is a template definition provided in the Magnolia Standard Templating Kit (STK). Its purpose is to render a news page.

virtualURIMapping

Defines mappings that redirect an incoming request to the actual location of the content.

Magnolia provides four ready-made classes that perform virtual URI mapping: default, regular expressions, rotating and host based.

Module structure

Since a Magnolia module is a Maven module, the file structure follows the typical Maven file structure:

  • src/main/java for Java classes
  • src/main/resources for resources

Here is the tree of src/main/resources in Eclipse:

To use the special features of Magnolia modules, follow these conventions and place resources in known locations:

PathContents

/META-INF

If you have your own custom tag library put the tag library definition file (.tld) here.

/magnolia

Module descriptor file. Follow a naming convention like <module name>.xml.

(warning) For the name of the module use only the characters from the [a-zA-Z0-9-_] regex range.

/mgnl-bootstrap/<module name>

XML files whose contents you want to be imported into the system when the module is installed.

/mgnl-bootstrap-samples

XML samples whose contents you want to be imported into the system when the module is installed. If property magnolia.bootstrap.samples is set to false these files are not imported.

/mgnl-files

Files in this folder are copied to the web application folder. Folder hierarchy is also copied. JSP files must go into this folder.

/mgnl-resources

Static resources such as style sheets and JavaScript. They will be available at URI /.resources, for example /.resources/example/style.css. You can access the resources from a Freemarker script with $(contextPath)/.resources/example/style.css.

Module descriptor

A module descriptor is a Magnolia-specific XML file that identifies and defines the module. When you start Magnolia, the system identifies available modules by locating each module's descriptor file. See Module descriptor for more.