Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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 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. |
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 .)
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:
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.
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 |
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 .
4 Comments
Christian Hamm
Regarding the Module class bean properties:
Can you please provide an example how to access the fields from the class programmatically? Can you provide an example on how to configure and access the fields via YAML?
Christoph Meier
Hi Christian
how to access the fields from the class programmatically:
- I will adapt / extend the docu after holidays to show the example.
See this class on git.
I have created this project especially for you
Feel free to check out the complete example my-little-module. It has the module property
foo
as shown above plus an additional one calledlittleBean
.how to configure and access the fields via YAML?
You cannot configure module properties via YAML; and you cannot access module bean properties in YAML files.
I hope this helps a bit.
Cheers and happy xmas - (santa)
Christoph
Christian Hamm
Got it! Thanks for the example code on how use the ModuleRegistry. Having the possibility to use YAML as a module configuration option would make life easier though
Christoph Meier
I'm glad you liked it.
Concerning YAML: There is the possibility to create / use YAML-based module descriptor - however, it has less possibilities compared to XML-based module descriptor. Feel free to use the Suggestion Box for new features.
BUT: Please note that the Module class bean properties as described on this page are not related to module descriptor. The properties are defined in the Module class. And to have a module class - you must have a Magnolia Maven module.