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.
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-form. When Maven module is meant, we write Maven 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:
- Is a Maven module too. But a Maven module is not a Magnolia module.
- Is specified by its module descriptor file.
- May have a dedicated module class.
- May install configuration from the
- May install sample data from the
- May have a module version handler.
- May install apps.
- May have its own JCR workspaces.
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:
Details and examples
|Defines 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.|
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.
Module-specific configuration which will be available via the module class (see below).
Config contains parameters and data for your module.
Define a configured dialog.
Dialog to edit the content of sample text & image of component.
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.
|Defines the display and allowed operations of a message.|
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.
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.
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.
Since a Magnolia module is a Maven module, the file structure follows the typical Maven file structure:
src/main/javafor Java classes
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:
If you have your own custom tag library put the tag library definition file (.tld) here.
Module descriptor file. Follow a naming convention like
For the name of the module use only the characters from the
XML files whose contents you want to be imported into the system when the module is installed.
XML samples whose contents you want to be imported into the system when the module is installed. If property
Files in this folder are copied to the web application folder. Folder hierarchy is also copied. JSP files must go into this folder.
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.