Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
Magnolia module configuration defines items such as templates and apps that can be used by other modules. A Magnolia module may have a module descriptor which configures things such as a module class. The module class can then configure its own properties, using the Node2Bean mechanism.
Configuration items
Configuration item | Purpose |
---|---|
apps | optional, YAML supported 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. |
| optional Define commands to use with the Magnolia command management. |
| optional Module-specific configuration which will be available via the module class (see Module properties). |
| optional, YAML supported To edit the content. |
| optional, YAML supported See Fields for further details about how to define your own field type. |
| optional, YAML supported To configure the display of the message and operations that editors can do. (see Message views). |
| optional It is possible to create a custom renderer - also for another templating language, e.g. Velocity. (Magnolia ships with JSP and FreeMarker template renderers.) |
| optional, YAML supported Templates can be pages or components. They can use FreeMarker, JSP or a custom templating language. |
traits | optional A trait is an attribute or property of a visitor or visit, such as age or gender, that you can use to personalize content. |
| optional Defines mappings that redirect an incoming request to the actual location of the content. |
Configuring in JCR vs YAML
Some of the configuration items (above) can be stored as JCR nodes or in YAML files. Storage in JCR nodes is possible for all items whereas not all items support YAML. (Items which cannot be stored yet as YAML files may get YAML support in future Magnolia versions.)
Both JCR nodes and YAML files are observed. Changes on the data is detected, object representations will be changed in their associated registries. (For instance a change in a template definition will re-register or update the TemplateDefinition in TemplateDefinitionRegistry .)
JCR nodes
In JCR context module configuration items are stored as nodes in the configuration
workspace. Use Configuration app to add, edit or delete JCR based configuration. The items ares stored under /modules/<module-name> - for instance /modules/myModule/templates.
JCR configuration nodes are observed with functions provided by Observation module.
Benefits:
- Supports all configuration items.
- Changes can be activated to other instances.
- Supports the extends mechanism.
YAML files
YAML configuration files reside in their corresponding folders within the module. For instance <module-name>/templates is the folder for the templates (see Module subfolders).
To add, edit or delete a YAML file use any text editor of your choice. Editors such as Brackets or Sublime text also support syntax highlighting.
Directories meant for YAML based configuration data are observed via DirectoryWatcherService .
Benefits:
Text files are human readable and easy to compare. Makes collaboration easier.
No need to export. Files are already part of the project lifecycle.
- No need for version handlers for updates.
- Easy to uninstall.
- Supports the include mechanism.
Location of configuration items
Item | YAML file path | JCR node path in config workspace |
---|---|---|
Template definition |
| /modules/<module-name>/templates |
Page template definition | $magnolia.resources.dir/<module-name>/templates/pages | /modules/<module-name>/templates/pages |
Component template definition | $magnolia.resources.dir/<module-name>/templates/components | /modules/<module-name>/templates/components |
Dialog definition | $magnolia.resources.dir/<module-name>/dialogs | /modules/<module-name>/dialogs |
App descriptor |
| /modules/<module-name>/apps |
Module class bean properties
Your module may have a module class. This class is the "root" bean of the configuration of your module. This means you can add bean properties to the class. When the module is loaded the Node2Bean mechanism will read property values from the configuration and set them in the instance of the module class.
Node name | Value |
---|---|
modules | |
my-module | |
config | |
foo | bar |
A bean in Magnolia configuration can have three states, which are represented by the value of a Boolean property called enabled
:
enabled = true
(default in most cases, there's no need to set this).enabled = false
enabled = null
, in which case the bean's configuration is either undefined or inherited - merged with its parent, for example when an area from a page template definition can get its values from a prototype.
When using the module class for configuration, create the module configuration in the /modules/<name-of-your-module>/config
directory. Bootstrap this data to ensure proper installation and setting of the config
node.
public class MyModule { /* You can optionally implement info.magnolia.module.ModuleLifecycle */ private String foo; public String getFoo() { return foo; } public void setFoo(String foo) { this.foo = foo; } }
Bean properties can be more complex, nested objects.
If you want to control processes during the start and stop phase of the module, implement ModuleLifecycle .