Page tree
Skip to end of metadata
Go to start of metadata

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.

commands

optional

Define commands to use with the Magnolia command management.

config

optional

Module-specific configuration which will be available via the module class (see Module properties).

dialogs

optional, YAML supported

To edit the content.

fieldTypes

optional, YAML supported

See  Fields  for further details about how to define your own field type.

messageViews

optional, YAML supported

To configure the display of the message and operations that editors can do. (see  Message views).

renderers

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

templates

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.

virtualURIMapping

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

ItemYAML file pathJCR node path in config workspace
Template definition

$magnolia.resources.dir/<module-name>/templates

/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

$magnolia.resources.dir/<module-name>/apps

/modules/<module-name>/apps

Location of configuration items

ItemYAML file pathJCR node path in config workspace
Template definition

$magnolia.resources.dir/<module-name>/templates

/modules/<module-name>/templates
Page template definition$magnolia.resources.dir/<module-name>/templates/pages/modules/<module-name>/templates/pages
Block template definition$magnolia.resources.dir/<module-name>/templates/blocks/modules/<module-name>/templates/blocks
Component template definition$magnolia.resources.dir/<module-name>/templates/components/modules/<module-name>/templates/components
Block definition$magnolia.resources.dir/<module-name>/blocks/modules/<module-name>/blocks
Dialog definition$magnolia.resources.dir/<module-name>/dialogs/modules/<module-name>/dialogs
App descriptor

$magnolia.resources.dir/<module-name>/apps

/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 nameValue
 modules
 

 my-module

 

 config

 

 foo

bar

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.

MyModule.java
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 .