Modules

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:

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 src/main/resources/mgnl-bootstrap/<module-name> directory.
May install sample data from the src/main/resources/mgnl-bootstrap-samples/<module-name> directory.
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:

Node name	Value
modules
rssaggregator
apps
fieldTypes
dialogs
config
commands
virtualURIMapping
templates

Folders:

Configuration item	Purpose	Details and examples
`apps`	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.
`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:

Path	Contents
`/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`. 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.

Page tree