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



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.



Define commands to use with the Magnolia command management.



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).



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.



A trait is an attribute or property of a visitor or visit, such as age or gender, that you can use to personalize content.



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

Configuring in JCR vs YAML

Some of the above mentioned configuration items 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 version.)

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.


  • 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 .


  • 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

ItemYAML file pathJCR node path in config workspace
Template definition


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



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 nameValue







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) { = 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 .


#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))