Definition decoration is a mechanism which allows you to change existing
configured items such as apps, dialogs, field types and templates. This
page explains the definition decoration concept and provides usage
examples.
Definition decoration concept
Definition decoration is a mechanism that allows you to change the
properties and subdefinitions of an existing definition item.
Most (but not all) of these items can be configured via YAML. All
items which can be configured via YAML are registered in a specific
registry. Registered items can be seen in the
Definitions app.
It is possible to change definitions such as app descriptors, dialogs,
field types, message views, templates, media editors and renderer
definitions. Any definition bound to info.magnolia.config.registry.Registry such as
info.magnolia.rendering.template.registry.TemplateDefinitionRegistry
can be decorated.
Decorated definitions can originate from any source, including the JCR,
YAML files or even executable code like Blossom. However, decorators
themselves can only be defined via YAML for the
time being.
Multiple decorations
The same definition can be decorated multiple times. When a definition
is decorated several times, the decorators are applied in the following
order:
Decorators from Magnolia Maven modules are applied before
decorators from light modules. (A Magnolia Maven module is a Maven packaged module which contains a Magnolia Module descriptor.)
If there are decorators from different Magnolia Maven modules, they
are applied in the dependency order of modules declaring the decorators.
The Module descriptor defines
Module dependencies. If module-a
depends on module-b, module-b is loaded before module-a. The module
dependencies of all Magnolia Maven modules together define a distinct
order.
If there are decorators from different Magnolia light modules, the
application order can be unpredictable. You can make it predictable by
defining the module loading order of your light modules in the
module descriptor.
When two decorators are decorating the same part of a definition, the last decoration applied wins, however, keep in mind that decorations are applied in the
module load order. Find out more about module dependencies and their loading order over here.
Decorating for merging or overriding
Definition decoration changes properties and subdefinitions of an
existing definition item. This change can either merge the decoration
with the decorated definition or completely override it. In the latter
case, you must use the YAML !override directive.
The only way to remove an existing decoration is to either override it with another decoration or remove the whole module with the original decoration.
Definition decorator file location
Definition decorator files must be stored in the decorations folder of
a module. The module can be either a Maven module or a light module (see
Module structure). This means that it is
possible to decorate definitions using the
light development
approach.
The definition decorator resolution mechanism requires decorator file
paths correspond to the following pattern:
<decorating-module-name>: Module which declares the definition
decorator.
decorations: Decorations folder within the decorating module.
<target-module-name>: Name of the module that hosts the targeted
items to decorate.
<definition-type>: Title of the registry containing definitions,
such as apps, dialogs, fieldTypes, messageViews, templates, mediaEditors
and renderers.
<def-relative-path>: Path to the decorated definition within the
target module, such as /pages or /components (for templates).
<def-name>: Name of the decorated definition, e.g. pages for the
name of an app.
<path-within-definition>: Path of the decorated subdefinition, such
as dam.subApps.
Definition decorator files are loaded in the same way as any other
Magnolia resource. See Resources for more.
Magnolia’s resource change observation mechanism ensures that definition
decorators are updated, registered and un-registered in real time,
without the necessity of a server restart. (To monitor changes in files
coming from the classpath, you must enable the magnolia develop mode,
see watching changes of resources).
The effect of a decorator addition, removal or modification is visible
on the next decorated definition retrieval attempt.
(Screenshot taken from the
Definitions app, which shows
definition items read from the corresponding registry. Also, notice the
presence of the tick in the Is decorated? column and on the row with
dam.)
Changing the cssFiles property in the mtk page template basic