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.

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. 

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

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. 

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

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

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

rootPath: /cars/007-cars

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

Add a css file to the mtk page template basic

cssFiles:
  chmStyles:
    link: /.resources/my-module/css/chm-style.css

chmStyles:
  link: /.resources/my-module/css/chm-style.css

Overriding properties and changing subitems

To understand the above statement, let's have a look at an example of a (simplified) template definition:

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

The consequence is that you cannot remove the css file /.resources/mtk/css/normalize-3.0.3.css. However, as a workaround, you could do something like this:

normalize:
  link: ""