...
A dialog file which includes:
Code Block |
---|
language | yamlyml |
---|
title | /module-a/dialogs/components/another-component.yaml |
---|
linenumbers | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogs/components/another-component.yaml?at=master |
---|
|
...
Include and modify a fragment
Include one tab in the form
and all the action definitions in the action
in a dialog definition. This is similar as in the example above. Additionally, modify the included parts of the definition.
This example works only with the new syntax (see syntactic variants).
Includable files:
Code Pro |
---|
|
language | yml |
---|
title | form:
label: another-component
tabs:
- name: tabMain
label: Main
fields:
- name: title
label: Text
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
label: Title
# an include within a list, here adding a complete tab
- !include:/module-a/includes/categorization-tab.yaml | collapse | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/includes/categorization-tab.yaml?at=master |
---|
Code Pro |
---|
language | yml |
---|
title | /module-a/includes/common-actions.yaml |
---|
collapse | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/includes/common-actions.yaml?at=master |
---|
|
A dialog file which includes:
# an include within a map, here adding the actions for the root (map) item "actions"
actions: !include:/module-a/includes/common-actions.yaml |
Anchor |
---|
| example-include-and-modify |
---|
| example-include-and-modify |
---|
|
Include and modify a fragment
Include one tab in the form
and all the action definitions in the action
in a dialog definition. This is similar as in the example above. Additionally, modify the included parts of the definition.
This example works only with the new syntax (see syntactic variants).
Includable files:
Multiexcerpt |
---|
MultiExcerptName | YAML-include-example |
---|
|
Code Pro |
---|
| yaml | dialogs | components/lazy | component | linenumberscollapse | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/ |
---|
| dialogs | components/lazy | component | - Line 6: Modify the label of the included tab.
- Lines 9 and 10: Modify the label of the
blackOrWhite
field from the include. - Lines 14 to 16: Add another action to the imported actions.
Include a complete file and modify
Create a dialog based on a dialog from the basic
page template of the mtk module. Remove its second tabMeta
tab. This task is similar to the example above in the modify section, but instead of inheriting, you include.
Code Pro |
---|
language | yml |
---|
title | /module-a/includes/common-actions.yaml |
---|
collapse | true |
---|
url | https://git.magnolia- |
---|
|
Code Pro |
---|
language | yaml |
---|
title | /module-a/dialogs/pages/aa-page.yaml |
---|
linenumbers | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogsincludes/pages/aacommon-pageactions.yaml?at=master |
---|
|
...
A dialog file which includes:
...
YAML inherit
As the name suggests, with this directive you inherit from an existing registered definition item in order to create a new definition item. Registered items can originate from YAML files, JCR configurations or even from Blossom Java code.
Warning |
---|
It is not a good idea to inherit from a definition which resides in the same module as the dependent one. Module files are loaded in order of discovery, which however varies 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 hence load correctly. Due to this behavior, you should not create such dependencies as they are inherently – no pun intended – unstable. |
You can inherit only on 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" which is unique among all items of the same type within their registry. Some of the items are defined by name, others by ID. Reference the item to inherit by its identifier.
Inherited items are inherited according to their state known by the registry. (For instance, if an items has been decorated, the registry knows its decorated state. Hence inheriting a decorated item inherits the decorated state of the item.)
...
title | Click here to expand for a list of definition item examples and their identifiers. |
---|
...
Template definitions
...
Dialog definitions
...
Module dependencies due to !inherit
When using !inherit
, you may rely on a definition item which 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.
...
|
Code Block |
---|
language | yml |
---|
title | /module-a/dialogs/components/lazy-component.yaml |
---|
linenumbers | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogs/components/lazy-component.yaml?at=master |
---|
| form:
label: lazy-component
tabs:
# an include within a list, here adding a complete tab
- !include:/module-a/includes/categorization-tab.yaml
label: Yo! 1-tab-only!
fields:
# modify properties of the field blackOrWhite which comes from the include
- name: blackOrWhite
label: Choose color
# an include within a map, here adding the actions for the root (map) item "actions"
actions: !include:/module-a/includes/common-actions.yaml
# add another action to those which already exist from the include
doit:
label: Same as cancel
class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition |
- Line 6: Modify the label of the included tab.
- Lines 9 and 10: Modify the label of the
blackOrWhite field from the include. - Lines 14 to 16: Add another action to the imported actions.
|
Include a complete file and modify
Create a dialog based on a dialog from the basic
page template of the mtk module. Remove its second tabMeta
tab. This task is similar to the example above in the modify section, but instead of inheriting, you include.
Code Block |
---|
language | yml |
---|
title | /module-a/dialogs/pages/aa-page.yaml |
---|
linenumbers | true |
---|
|
...
Module dependencies can be defined within a module descriptor.
A 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.
Examples
Inherit and override a renderer
A new definition:
Multiexcerpt |
---|
MultiExcerptName | YAML-inherit-simpleExample |
---|
|
Code Pro |
---|
language | yaml |
---|
title | /module-a/renderers/json.yaml | url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogs/ |
---|
| renderers | json | The new renderer named json
inherits everything from the freemarker
renderer but has a different contentType.
Inherit and override a template definition
The original definition you inherit from:
...
language | yaml |
---|
title | /module-a/templates/components/a-component.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/templates/components/a-component.yaml?at=master |
---|
!include:/mtk/dialogs/pages/basic.yaml
form:
tabs:
- name: tabMeta
fields: !override |
YAML inherit
As the name suggests, with this directive you inherit from an existing registered definition item in order to create a new definition item. Registered items can originate from YAML files, JCR configurations or even from Blossom Java code.
Warning |
---|
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 however varies 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 hence load correctly. Due to this behavior, you should not create such dependencies as they are inherently – no pun intended – unstable. |
You can inherit only on 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" which is unique among all items of the same type within their registry. Some of the items are defined by name, others by ID. Reference the item to inherit by its identifier.
Inherited items are inherited according to their state known by the registry. (For instance, if an items has been decorated, the registry knows its decorated state. Hence inheriting a decorated item inherits the decorated state of the item.)
Expand |
---|
title | Click here to expand for a list of definition item examples and their identifiers. |
---|
|
|
Module dependencies due to !inherit
When using !inherit
, you may rely on a definition item which 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.
Include Page |
---|
| _Module dependencies define module loading order |
---|
| _Module dependencies define module loading order |
---|
|
Module dependencies can be defined within a module descriptor.
A 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.
Examples
Inherit and override a renderer
A new definition:
Multiexcerpt |
---|
MultiExcerptName | YAML-inherit-simpleExample |
---|
|
|
A new definition which inherits:
...
language | yaml |
---|
title | /module-b/templates/components/b-component.yaml |
---|
linenumbers | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-b/templates/components/b-component.yaml?at=master |
---|
- 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
...
language | yaml |
---|
title | /module-b/module.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-b/module.yaml?at=master |
---|
By setting this dependency, we make sure that module-a
is loaded before module-b
. As a result, the b-component
, which depends on a-component
, can be initialized properly.
...
Modifying reused configuration
Reused configuration originating from !inherit
or from !include
(when using the new !include
syntax) can be modified. You can:
- Add additional properties 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 further properties to the given node.
YAML override
Info |
---|
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:
...
...
renderers/json.yaml | url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/ |
---|
|
|
...
renderers/json.yaml?at=master |
|
|
...
!inherit:freemarker
contentType: application/json |
The new renderer named json inherits everything from the freemarker renderer but has a different contentType. |
Inherit and override a template definition
The original definition you inherit from:
...
...
...
...
component.yaml | url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/templates/ |
---|
|
...
...
...
...
...
title: a-component
renderType: freemarker
templateScript: /module-a/templates/ |
...
...
...
component.ftl
dialog: module-a:components/a-component
modelClass: info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel
parameters:
color: blue
size: 50 |
A new definition which inherits:
Code Block |
---|
language | yml |
---|
title | /module-b/templates/components/b-component.yaml |
---|
linenumbers | true |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-b/templates/components/b-component.yaml?at=master |
---|
|
!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
Code Block |
---|
language | yml |
---|
title | /module-b/module |
---|
|
Overriding list items
Tip |
---|
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:
...
.yaml | url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module- |
---|
|
...
|
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, the b-component
, which depends on a-component
, can be initialized properly.
Anchor |
---|
| modify-reused-items |
---|
| modify-reused-items |
---|
|
Modifying reused configuration
Reused configuration originating from !inherit
or from !include
(when using the new !include
syntax) can be modified. You can:
- Add additional properties 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 further properties to the given node.
YAML override
Info |
---|
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:
A definition to inherit or to include | Inherit | Inherit and override |
---|
Code Block |
---|
language | yml |
---|
title | /module-a/templates/pages/l-page.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/templates/pages/l-page.yaml?at=master |
---|
| title: L page
templateScript: /mtk/templates/pages/basic.ftl
renderType: freemarker
dialog: module-a:pages/l-page
visible: true
areas:
main:
availableComponents:
textImage:
id: mtk:components/textImage
teaser:
id: mtk:components/teaser
image:
id: mtk:components/image
link:
id: mtk:components/link |
| Code Block |
---|
title | /module-a/templates/pages/xxl-page.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/templates/pages/xxl-page.yaml?at=master |
---|
| !inherit:module-a:pages/l-page
title: XXL page
dialog: module-a:pages/xxl-page
areas:
main:
availableComponents:
html:
id: mtk:components/html |
| Code Block |
---|
language | yml |
---|
title | /module-a/templates/pages/xs-page.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/templates/pages/xs-page.yaml?at=master |
---|
| !inherit:module-a:pages/l-page
title: XS page
dialog: module-a:pages/xs-page
areas:
main:
availableComponents: !override
link:
id: mtk:components/html |
|
| The resulting definition merges the inherited defintion and the modifications area, giving five available components in the main area. | The resulting definition ignores all the properties of availableComponents of the inherited definition, thus allowing only one available component in the main area. |
Overriding list items
Tip |
---|
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:
A definition to inherit or to include | Inherit |
---|
Code Block |
---|
language | yml |
---|
title | /module-a/dialogs/pages/l-page.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogs/pages/l-page.yaml?at=master |
---|
| form:
label: Page properties
tabs:
- name: tabMain
label: L page
fields:
- name: title
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
i18n: true
label: title
- name: navigationTitle
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
i18n: true
label: navigation title
- name: windowTitle
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
i18n: true
label: window title
- name: tabMeta
label: Meta Data
fields:
- name: keywords
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
i18n: true
label: keywords
rows: 3
- name: description
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
i18n: true
label: description
rows: 5
actions:
commit:
class: info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition
cancel:
class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition |
| Code Block |
---|
language | yml |
---|
title | /module-a/dialogs/pages/xs-page.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogs/pages/xs-page.yaml?at=master |
---|
| !include:/module-a/dialogs/pages/l-page.yaml
form:
tabs:
tabMeta: !override
tabMain:
fields:
title: !override
required: true
class: info.magnolia.ui.form.field.definition.RichTextFieldDefinition
label: Title ... | Code Pro |
---|
|
language | yaml |
---|
title | /module-a/dialogs/pages/xs-page.yaml |
---|
url | https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/having-fun-with-yaml/raw/light-modules/module-a/dialogs/pages/xs-page.yaml?at=master |
|
Both tabs and fields are defined with a list. To define these properties, it would have been valid to use the map syntax instead. | To apply !override to the tabMeta tab and the title field, we have used the map syntax here. |
...