Definition decoration

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.

A definition item is a configuration of a "component" to execute tasks in a Magnolia instance. Template definitions, dialog definitions, app definitions (also known as app descriptors), renderer definitions, themes definitions, field definitions are all examples of such definition items. They can be configured via JCR in the configuration workspace.

Most (but not all) of these items can be configured via YAML. A YAML-based configuration requires Magnolia version 5.4 or higher. 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 a Registry such as 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.

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.
If there are decorators from different Magnolia Maven modules, they are applied in the dependency order of modules declaring the decorators. **
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".

*) A Magnolia Maven module is a Maven packaged module which contains a Magnolia Module descriptor.
**) 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.

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 !override directive.

Have a look at Changing the cssFiles property in the mtk page template basic for examples of both merging and overriding.

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>/decorations/<target-module-name>/<definition-type>/<def-relative-path>/<def-name>.<path-within-definition>.yaml

<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 subapps.browser.contentConnector.

Magnolia maven module

Light module

my-maven-module/
└── src
    └── main
        └── resources
            └── my-module
                └── decorations
                    ├── dam-app
                    │   └── apps
                    │       └── assets.subApps.browser.contentConnector.yaml
                    ├── mtk
                    │   └── templates
                    │       └── pages
                    │           ├── basic.cssFiles.yaml
                    │           └── basic.yaml
                    └── pages
                        └── apps
                            └── pages.yaml

$magnolia.resources.dir
└── my-module
    └── decorations
        ├── dam-app
        │   └── apps
        │       └── assets.subApps.browser.contentConnector.yaml
        ├── mtk
        │   └── templates
        │       └── pages
        │           ├── basic.cssFiles.yaml
        │           └── basic.yaml
        └── pages
            └── apps
                └── pages.yaml

Definition decorator development in real time

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.

Decoration examples

Change the title and the icon of an app

/my-module/decorations/pages/apps/pages.yaml

label: My pages ...
icon: icon-user-me

Result:

Change the root path of the content connector of the assets app

/my-module/decorations/dam-app/apps/dam-app/assets.subApps.browser.contentConnector.yaml

rootPath: /cars/007-cars

Result:

(Screenshot was taken from the definition-app which shows definition items read from the corresponding registry.)

Changing the `cssFiles` property in the mtk page template `basic`

mtk/templates/pages/basic.yaml (excerpt)

templateScript: /mtk/templates/pages/basic.ftl
dialog: mtk:pages/basic
renderType: freemarker
class: info.magnolia.module.site.templates.PageTemplateDefinition
cssFiles:
  normalize:
    link: /.resources/mtk/webresources/css/normalize-3.0.3.css
  main:
    link: /.resources/mtk/webresources/css/html5boilerplate-main-5.3.0.css
  video:
    link: /.resources/mtk/webresources/css/video.css

The original template defines three CSS files.

a) Adding an additional CSS file - merging

/my-module/decorations/mtk/templates/pages/basic.yaml

cssFiles:
  minimum:
    link: /.resources/my-module/webresources/css/minimum.css

b) Overriding the property completely - using `!override`

/my-module/decorations/mtk/templates/pages/basic.yaml

cssFiles: !override
  minimum:
    link: /.resources/my-module/webresources/css/minimum.css

Page tree

Definition decoration