This page explains how to configure modules in Magnolia. Module configuration data is useful because:
- It can be accessed programmatically inside the same module and from other modules.
- It can be changed on a running system.
The explanation on this page applies to Magnolia Maven modules with a module class.
How it works
A Magnolia Maven module may contain a module class. The class needs to be specified in the module descriptor. See, for example, line 6 below:On the module class, you define module configuration properties as Java bean properties.
A bean in Magnolia configuration can have three states, which are represented by the value of a Boolean property called
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.
The property values the class defines may be default and are persisted in the configuration data. On module start-up or when configuration data changes, the system calls the properties setter methods to set the new values on the instance of the module class, using the values from the configuration data. Module configuration items are registered in the ModuleConfigurationRegistry. On a running system, you can use the Definitions app to check modules' configuration data.
Changing the configuration on a running system
If you change configuration data on a running system, Magnolia is notified about it. When the configuration data changes, the properties on the module class are reset accordingly and the configuration item is re-registered in the module configuration registry (ModuleConfigurationRegistry).
If your module requires a specific re-initialization for some custom components, implement ModuleLifecycle and add module-specific code in the
#stop interface methods. The system calls these methods, if it detects changes in the configuration data.
Typically, when changing configuration data of modules provided by Magnolia, there is no need to restart the instance.
Configuration data can be stored either in a YAML file or under a JCR node in the
config workspace. We recommend using a YAML file.
The structure of the configuration data depends on the bean properties defined on the module class.
The next subsection shows an example of configuration data for a hypothetical module class called
The YAML file containing module configuration data has to reside at
Changing module configuration
There are several ways to change an original configuration.
|In YAML file||In the JCR |
If the original configuration is a YAML file, do not create a node in the JCR
Decorating means adapting the current configuration. A decorator file can reside in any Magnolia Maven module or light module. In the example below, we create a decorator file in a light module called
test-module. In this module, create the
Creating a hotfix means utilizing the Magnolia Resources framework's capability which allows a resource to have different origins, see Resources - Origins and loading order. A hotfix:
- Is a representation of a resource in the JCR
- Has precedence over the YAML file in the
jarfile of the deployed module.
Utilizing the JCR
resources workspace can be useful for an administrator to apply a hotfix that is urgent. From a long-term perspective, however, we recommend that you keep your configuration and configuration changes in YAML files. This way they may become part of source control and are easier for large developer teams to work with.
To create a hotfix, follow these steps:
- Open the Resource Files app.
- Browse to
<your-module>and select the
- In the action bar, click Edit file. The Resource Files app creates a copy of the currently used configuration and stores it in the JCR
- Edit the file as necessary.
- Click Save changes.
(You may have to publish the resource node created to your author instances.)
Even though we recommend using YAML files for configuration data, there are still a lot of modules whose configuration is stored in the JCR
config workspace. Below is an example using the
ui-admincentral module, in which we change the
defaultGroup of the
- Open the Configuration app.
- Go to the
- Change the value of the
defaultGroupproperty. (Change other subnodes and properties as necessary.)
You also can add new nodes and properties, if they match with the defined bean properties of the module class.
Changes are applied automatically when you leave a field. (You may have to publish the node you changed to your author instances.)
Accessing configuration data programmatically
To access module configuration in a Java class, use
javax.inject.Provider to access the sole instance of your module class. On the module class instance, you can call the getter methods of the module bean properties.
- Line 10: Make the
javax.inject.Providera private final field of your class.
- Lines 12-14: Inject the
Providervia a constructor.
- Line 20: Get the singleton instance of your
- Lines 23-25: Access the bean properties of your module.