YAML inherit and include

This page describes the Magnolia-specific directives !inherit,!include and !override. With these directives, you can reuse YAML file-based configurations. !include allows you to reuse an arbitrary resource, whereas !inherit is useful for extending a definition.

YAML include

Use !include to add a reusable chunk. Include a YAML fragment one level below your new definition, or include a complete YAML definition on top of your new definition. You can also modify the included part of the definition.

Reference the file you want to include by its resource path. The path to such a resource has the following pattern: /<module-name>/path/to/the/reusable/chunk.yaml.

Typically, you include YAML snippets that are not proper definitions. Do not add snippets to folders that are meant for definitions (templates, dialogs, apps). Instead, add these snippets to a folder that is not scanned (for instance, /<your-module>/includes/).

If your !include file is not working, check that the first line in the included YAML file does not have any indentation.

Syntactic variants of the directive

The !include directive has existed since Magnolia 5.4, which introduced configuration by YAML. With the release of 5.5.6, the directive syntax has changed slightly. While the old syntax still works, the new one makes it possible to modify and override the included part of the definition. The new syntax uses a colon instead of a space between !include and the path to the resource.

Syntax Requires version Functions

	Syntax	Requires version	Functions
Deprecated syntax	`!include <path/to/a–ressource.yaml>`	Magnolia 5.4+	simple include
New syntax	`!include:<path/to/a–ressource.yaml>`	Magnolia 5.5.6+	simple include, include and modify

Deprecated syntax

!include <path/to/a–ressource.yaml>

Magnolia 5.4+

simple include

New syntax

!include:<path/to/a–ressource.yaml>

Magnolia 5.5.6+

simple include, include and modify

Generic recipe

Prepare a fragment that can be reused in many item definitions.
Include a resource with the !include directive. The included resource can contain a fragment or a complete definition.
Modify parts of the included definition.

Example definitions

Simple include

Include one tab and all the action definitions in a dialog definition.

This example works with both the old (deprecated) and the new syntax.

Includable files

/module-a/includes/categorization-fields.yaml

categories:
  $type: multiValueField
  label: Select category
  field:
    $type: linkField
    datasource:
      $type: jcrDatasource
      workspace : category
blackOrWhite:
  label: Black or white
  $type: comboBoxField
  datasource:
    $type: optionListDatasource
    options:
      - name: black
        value: black
        label: Black
      - name: white
        value: white
        label: White

A dialog file with includes

/module-a/dialogs/components/another-component.yaml

form:
  properties:
    !include:/module-a/includes/categorization-fields.yaml # an include within a list, add fields
    title:
      $type: textField
      label: Title

Include and modify a fragment

Include one tab and all the action definitions in a dialog definition. Additionally, modify the included parts of the definition.

This example works only with the new syntax (see syntactic variants).

Includable files

/module-a/includes/categorization-fields.yaml

categories:
  $type: multiValueField
  label: Select category
  field:
    $type: linkField
    datasource:
      $type: jcrDatasource
      workspace : category
blackOrWhite:
  label: Black or white
  $type: comboBoxField
  datasource:
    $type: optionListDatasource
    options:
      - name: black
        value: black
        label: Black
      - name: white
        value: white
        label: White

A dialog file with includes

/module-a/dialogs/components/lazy-component.yaml

form:
  properties:
    !include:/module-a/includes/categorization-fields.yaml # an include within a list, add fields
    blackOrWhite: # modify properties of the field blackOrWhite, which comes from the include
      label: Choose color

Include a complete file and modify

Create a dialog based on a dialog from the basic page template of the MTK module. Override its second tabMeta tab. This is similar to the example in the Modifying reused configuration section, but here you use !include instead of !inherit.

/module-a/dialogs/pages/aa-page.yaml

!include:/mtk/dialogs/pages/basic.yaml
form:
  tabs:
    - name: tabMeta
      fields: !override

YAML inherit

With this directive, you can inherit from an existing registered definition item in order to create a new definition item. Registered items can originate in YAML files or even Blossom Java code.

In Magnolia 6.3.x, YAML can no longer inherit from JCR-based definitions through the !inherit directive. This is because, in 6.3, we’ve overhauled the internals of our definition Registries and ConfigurationSources.

Workaround: You have to inline or migrate the JCR definitions into YAML instead.

Example error message pointing to this issue:

Inherited definition at [freemarker] either does not exist
or is not loaded because of the missing module dependency in module [block-templating],
which currently depends only on [core, templating, rendering, site]

Title: Missing definition dependency

It is not a good idea to inherit from a definition that resides in the same module as the dependent one.

Module files are loaded in order of discovery, which can vary over time. This means that after one reload, a definition might work while the next time you edit the definition or restart your application, it may fail to discover an intra-modular dependency and to load correctly. Due to this behavior, you should not create such dependencies as they are inherently unstable.

You can inherit only at the root level, which means you can inherit a complete app but not a subapp. Modify the new item according to your needs.

Registered definition items are known to a registry and can be seen in the Definitions app. Every registered definition item has an identifier that is unique among all items of the same type within their registry. Some items are defined by name, others by ID. To inherit an item, reference it by its identifier.

Items are inherited along with their state as known by the registry. For instance, if an item has been decorated, the registry knows its decorated state. Inheriting a decorated item means inheriting the decorated state of the item.

Item definition type Identifier type Example identifier

Item definition type	Identifier type	Example identifier
Template definitions	ID	`mtk2:components/link`
Dialog definitions	ID	`mtk2:components/textImage`
App definitions	Name	`definitions-app`
Theme definitions	Name	`travel-demo-theme`
Renderer definitions	Name	`freemarker`

Template definitions

mtk2:components/link

Dialog definitions

mtk2:components/textImage

App definitions

Name

definitions-app

Theme definitions

Name

travel-demo-theme

Renderer definitions

Name

freemarker

Module dependencies due to inherit

When using !inherit, you may rely on a definition item that is configured in another module. In this case, you must take care of the loading order. If you rely on another module, make sure it is loaded upfront. Use module dependencies to define the loading order of the modules.

The module dependencies define the order in which modules are loaded during startup. For example, if module-a depends on module-b, module-b will be loaded before module-a. The order becomes important, for example, if both module-a and module-b decorate the same definition or if module-a inherits a definition from module-b.

Module dependencies can be defined within a module descriptor.

Generic recipe

On the first line of your YAML definition, use the !inherit directive followed by a colon and the identifier of the definition you want to inherit from.
Modify the inherited definition.

Example definitions

Inherit and override a renderer

A new definition

/module-a/renderers/json.yaml

!inherit:freemarker
contentType: application/json

The new renderer named json inherits everything from the freemarker renderer but has different contentType.

Inherit and override a template definition

The original definition you inherit from

/module-a/templates/components/a-component.yaml

title: a-component
renderType: freemarker
templateScript: /module-a/templates/components/a-component.ftl
dialog: module-a:components/a-component
modelClass: info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel

parameters:
  color: blue
  size: 50

A new definition that inherits

/module-b/templates/components/b-component.yaml

!inherit:module-a:components/a-component
title: b-component
description: This is a b-bombastic component to test cool YAML features!
subtype: dummy-components
parameters: !override

Line 1: Inherit.
Line 2: Override the title property.
Lines 3 and 4: Add more properties.
Line 5: Suppress the parameters property.

The module descriptor of module-b

/module-b/module.yaml

version: 1.0
dependencies:
  module-a:
    version: 1.0/*

By setting this dependency, we make sure that module-a is loaded before module-b. As a result, b-component, which depends on a-component, can be initialized properly.

Modifying reused configuration

Reused configuration originating from !inherit or !include (when using the new !include syntax) can be modified. You can:

Add and modify properties originating from !include or !inherit. This will merge the included or inherited node with the modifications.
Use !override to completely ignore the properties of an inherited or included node. As a consequence, you have to add properties to the given node.

YAML override

The !override directive ignores the properties of the node to which the directive has been applied. You have to specify all of the required properties of the overridden definition node.

Example definitions

A definition to inherit or include

/module-a/templates/pages/l-page.yaml

title: L page
templateScript: /mtk2/templates/pages/basic.ftl
renderType: freemarker
dialog: module-a:pages/l-page
visible: true

areas:
  main:
    availableComponents:
      textImage:
        id: mtk2:components/textImage
      teaser:
        id: mtk2:components/teaser
      image:
        id: mtk2:components/image
      link:
        id: mtk2:components/link

Inherit

/module-a/templates/pages/xxl-page.yaml

!inherit:module-a:pages/l-page
title: XXL page
dialog: module-a:pages/xxl-page

areas:
  main:
    availableComponents:
      html:
        id: mtk2:components/html

The resulting definition merges the inherited definition and the modification’s area, rendering five available components in the main area.

Inherit and override

/module-a/templates/pages/xs-page.yaml

!inherit:module-a:pages/l-page
title: XS page
dialog: module-a:pages/xs-page

areas:
  main:
    availableComponents: !override
      link:
        id: mtk2:components/html

The resulting definition ignores all the properties of availableComponents in the inherited definition, rendering only one available component in the main area.

Overriding list items

Due to the syntax of a YAML list, you cannot apply !override to a list item. To bypass this constraint, use a YAML map instead of a list to apply !override to an item. Even if the definition class expects a list, the YAML file can define the item with a map.

Example definitions

A definition to inherit or include

/module-a/dialogs/pages/l-page.yaml

form:
  properties:
    title:
      $type: textField
      i18n: true
      label: title
    navigationTitle:
      $type: textField
      i18n: true
      label: navigation title
    windowTitle:
      $type: textField
      i18n: true
      label: window title
    keywords:
      $type: textField
      i18n: true
      label: keywords
      rows: 3
    description:
      $type: textField
      i18n: true
      label: description
      rows: 5
  layout:
    $type: tabbedLayout
    tabs:
      tabMain:
        fields:
          - name: title
          - name: navigationTitle
          - name: windowTitle
      tabMeta:
        fields:
          - name: keywords
          - name: description

Include and override

/module-a/dialogs/pages/xs-page.yaml

!include:/module-a/dialogs/pages/l-page.yaml
form:
  properties:
    title: !override
      required: true
      $type: richTextField
      label: Title ...
  layout:
    tabs: !override
      tabMain:

We apply !override to both title and tabs in the example definition above.

When overriding a bracketed list you must put the override directive between the key and list. An example is given below.

Original

protocol: [ 'http', 'https' ]

Override

protocol: !override
[ 'https' ]

Preserving the order of nodes

The order of nodes as defined in a decoration via !override is preserved. This is useful especially if the only change needed to the existing configuration of nodes is their order. Previously, when providing a new configuration with !override, the configuration would be picked up by the system, but any change in the order of the nodes (at the level of the !override) would not be respected.

For example, the list view in the workbench of the Tours app may be adjusted with the following definition decoration placing the path column before the name column:

/stories-app/decorations/tours/apps/tours.yaml

subApps:
  browser:
    workbench:
      contentViews:
        list:
          columns: !override
            path:
            name:

YAML inherit and include

YAML include

Syntactic variants of the directive

Generic recipe

Example definitions

Simple include

Include and modify a fragment

Include a complete file and modify

YAML inherit

Module dependencies due to inherit

Generic recipe

Example definitions

Inherit and override a renderer

Inherit and override a template definition

Modifying reused configuration

YAML override

Example definitions

Overriding list items

Example definitions

Preserving the order of nodes

Location

Main doc sections