YAML
This page describes Magnolia’s main uses of YAML, a data serialization format designed for human readability and interaction with scripting languages:
-
Using YAML to define items such as templates, dialogs, and apps.
-
Using YAML for exporting and importing JCR content.
Benefits of YAML
YAML is the preferred way to define (configure) templates, dialogs, apps and other definition items in Magnolia.
-
YAML is less difficult to work with in typical development cases such as diffing and merging. A YAML file is basically just a text file.
-
The format is easier to read and edit, the content and overall structure is more readily visible to the user, e.g. importing multi-line quotes and special character needs no escaping.
-
It enables easier creation of JCR import files from other data sources.
To parse YAML data, Magnolia uses snakeyaml. The data is
transformed by the info.magnolia.map2bean.Map2BeanTransformer
.
YAML as definition files
YAML files are primarily meant to define (configure) items such as apps, templates, dialogs.
Example: A YAML definition of a helloworld
app.
appClass: info.magnolia.ui.app.helloworld.HelloWorldApp
class: info.magnolia.ui.api.app.registry.ConfiguredAppDescriptor
icon: icon-app
label: Hello World
What can be defined via YAML?
Items defined in the configuration
workspace
can
be downloaded as YAML to move the configuration into a file.
In a running system, the data written in YAML is represented by a Java Bean. The following table lists Magnolia YAML files and their corresponding Magnolia classes, usually called definition or description classes.
Item | YAML file | Corresponding definition class* |
---|---|---|
Dialog |
|
info.magnolia.ui.dialog.DialogDefinition |
Template |
|
info.magnolia.rendering.template.TemplateDefinition |
App |
|
info.magnolia.ui.api.app.AppDescriptor |
-
You can also use custom definition classes which will usually extend the classes mentioned above. In this case you have to provide the class as an attribute in the YAML file.
Deprecating a YAML-based definition with !metadata
The introduction of the
info.magnolia.config.source.yaml.construct.WrapMetadata
construct in
Magnolia 5.6.2 allows you to deprecate YAML-based definitions. You can
mark a YAML-based definition as deprecated like this:
deprecated: !metadata
since: 5.5.6
description: The dialog uses the deprecated PlaceholderTextFieldDefinition. Please use the placeholder property instead.
The deprecated definition is displayed in the Definitions app. Currently, the app reports the following deprecated (or non-existing) items:
-
Deprecated classes used by any definition.
-
Deprecated or non-existing templates used by block definitions.
-
Deprecated or non-existing page template definitions referenced from site definitions.
-
Deprecated or non-existing theme definitions referenced from site definitions.
-
Template references.
-
Deprecated or non-existing dialogs
-
Deprecated or non-existing component definitions used in page definitions.
-
Non-existing template script paths.
-
Configured but non-existing renderer.
-
Reusing configuration in YAML files with !inherit
and !include
Magnolia provides two mechanisms to reuse a configuration within a
YAML-file: !inherit
and !include
. You can use them not only to reuse
a definition but also to modify a reused definition.
YAML inherit
Use the Magnolia !inherit
directive to inherit a registered definition
item in order to create a new definition item, and then
modify
the new item according to your needs. This directive is very similar to
JCR extends. The
item you inherit the definition from is referenced by its identifier.
Example:
!inherit:freemarker
contentType: application/json
The new renderer named json
inherits everything from the freemarker
renderer but has a different contentType.
For more information read the YAML inherit and include page. |
YAML include
Use the Magnolia !include
directive to add a reusable YAML chunk.
Include a fragment on a sub-level of your new definition or include a
complete definition on top of your new definition. Reference the file
you include by its resource path. The path
to such a resource has the following pattern:
/<module-name>/path/to/the/reusable/chunk.yaml
.
You can also modify the included part of the definition.
If your |
Syntactic variants of the directive
The !include
directive exists since Magnolia 5.4, which introduced
configuration by YAML. However, the directive’s syntax has changed
slightly with the release of Magnolia 5.5.6. 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 the
space between !include
and the path to the resource.
Syntax | Requires version | Functions | |
---|---|---|---|
Deprecated syntax. ( WARNING: Magnolia 5.5.6+) |
|
Magnolia 5.4+ |
simple include |
New syntax. |
|
Magnolia 5.5.6+ |
simple include, include and modify |
For more information read YAML inherit and include. |
Reusing an existing definition within the same file
YAML’s anchor property and alias indicator make it possible to reuse an already existing definition by referencing it.
In the following definition, for example, the anchor
&footerAvailableComponents
and the alias
*footerAvailableComponents
allow reusing the
components defined in the footer
area also in the main
area:
templateScript: /mtk2/templates/pages/basic.ftl
dialog: mtk2:pages/basic
renderType: freemarker
class: info.magnolia.module.site.templates.PageTemplateDefinition
areas:
footer:
inheritance:
components: all
enabled: true
availableComponents: &footerAvailableComponents
textImage:
id: mtk2:components/textImage
image:
id: mtk2:components/image
main:
availableComponents: # using all components from footer plus others
<<: *footerAvailableComponents
html:
id: mtk2:components/html
linkList:
id: mtk2:components/linkList
See also the magnolia.yaml.maxAliasesForCollections property.
|
Definition decoration
With some restrictions related to overriding properties and changing subitems, YAML is currently the only way to decorate already existing definitions. For more details see Definition decoration page.
Defining a list property via YAML map or list syntax
In a YAML file, when a property type is defined as a list in the corresponding Java class, you can use the map syntax or the list syntax. info.magnolia.map2bean.Map2BeanTransformer converts YAML in both cases correctly.
Java definition class
info.magnolia.ui.form.FormDefinition (simplified)
public interface FormDefinition<T> extends EditorDefinition<T> {
List<EditorPropertyDefinition> getProperties();
}
In the given example, the type of items that go onto the list extend
info.magnolia.config.NamedDefinition, which is very
typical for any (sub-)item definition class. This means that items going
onto the list must define a name
property.
List syntax
form:
properties:
- name: salutation
class: info.magnolia.ui.field.TextFieldDefinition
- name: firstName
label: first name
class: info.magnolia.ui.field.TextFieldDefinition
With the list syntax, you typically start with the name
sub-property.
Map syntax
form:
properties:
salutation:
label: salutation
class: info.magnolia.ui.field.TextFieldDefinition
firstName:
name: givenName
label: first name
class: info.magnolia.ui.field.TextFieldDefinition
With the map syntax, the map keys (lines 3 and 6) are used as the name
property by Map2BeanTransformer. You can override it by setting the
name
property explicitly (line 7).
YAML for importing and exporting JCR content
YAML can also be used to export and import JCR content, which was originally possible only with XML files.
Example: An export of a simple page node in YAML format
'my-page':
'hideInNav': false
'title': 'This is my page'
jcr:primaryType: 'mgnl:page'
jcr:uuid: '701efb1f-c53b-4830-87b5-873776798d80'
mgnl:created: 2017-05-10T11:40:24.968+07:00
mgnl:createdBy: 'superuser'
mgnl:lastModified: 2017-05-10T11:40:34.569+07:00
mgnl:lastModifiedBy: 'superuser'
mgnl:template: 'mtk2:pages/basic'
Syntax
For a complete reference of the YAML syntax please refer to http://yaml.org/ or http://www.yaml.org/refcard.html. The following syntactic elements are the most widely used though.
-
Whitespace indentation is used to denote structure; however tab characters are never allowed as indentation.
-
Comments begin with the number sign (
#
), can start anywhere on a line and continue until the end of the line. Comments must be separated from other tokens by white space characters. -
Strings (scalars) are ordinarily unquoted, but may be enclosed in double-quotes (
"
), or single-quotes ('
).
Sequences
Members of a sequence are lines beginning at the same indentation level,
and starting with a leading hyphen and at least one space (-
). The
number of spaces after the leading hyphen must be the same for all
members in the sequence.
# A list of food
- Sandwich
- Pizza
- Burrito
- Chocolate cake
Mappings
Mappings (also known as dictionaries in YAML, or just maps
informally) are represented in a simple
key:
``value
form (the colon must be followed by a
space):
# An employee record
name: John Doe
job: Developer
skill: Beginner
Using empty values in sequences and mappings
If you need to set an empty value in a map or sequence, use the empty brackets notation as shown in the following examples:
list: []
map: {}
A null value used in the way as on line 5 below is reported as a warning
with severity level minor
in the
Definitions app.
areas:
main:
type: list
renderType: freemarker
availableComponents:
Combinations of mappings and sequences
Let’s combine some mappings and sequences, which is a common use case in Magnolia YAML files.
---
# An employee record
name: John Doe
job: Developer
skill: Beginner
employed: True
food:
- Sandwich
- Pizza
- Burrito
- Chocolate cake
drinks: [coke, beer, water, milk] # this is an example of another notation for a sequence
languages:
groovy: Beginner
java: Beginner
freeMarker: Expert
|
YAML file size
SnakeYAML 1.32 restricts the size of YAML files to a maximum of approximately 3 MB
to prevent any potential issues with untrusted sources.
This file limit size could break existing setups if you use any YAML files that are larger than this accepted limit. |
We recommend using XML bootstrap format for bigger exports. They do not have a maximum size limit. |
Since Magnolia 6.2.31, exporting such large YAML files is prevented and instead fallbacks to an XML export format. |
Further resources about YAML
YAML specification and documentation
-
yaml.org (The Official YAML Web Site)
-
Index of YAML terms (YAML 1.2)
-
A reference card (YAML 1.1)
-
snakeyaml (the YAML parser used by Magnolia)
Editors supporting YAML syntax
-
IntelliJ (with plugin)
Online YAML tools
-
Parsers and linters
-
Converters
Check out our partner’s Magnolia YAML assistant IntelliJ plugin to increase your efficiency in Magnolia light development.
— Ray Sono AG
|