Page tree
Skip to end of metadata
Go to start of metadata

This page describes Magnolia's main uses of YAML, a data serialization format designed for human readability and interaction with scripting languages:

  1. Using YAML to define items such as templates, dialogs, and apps.
  2. Using YAML for exporting and importing JCR content.


The two uses of YAML in Magnolia

Before Magnolia 5.4, the only way to define (configure) templates, dialogs, apps and other definition items was only through JCR in the configuration workspace. The 5.4 release brought configuration via YAML as another possibility, mainly because:

  • YAML is less difficult to work with in typical development cases such as diffing and merging.
  • 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.

With the release of Magnolia 5.5.4, importing and exporting JCR data can be done with YAML files. Until then this was possible only in the XML format.

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

ui-helloworld-app/apps/helloworld.yaml
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. 

ItemYAML fileCorresponding definition class*
DialogmyDialog.yaml
DialogDefinition
TemplatemyTemplate.yaml
TemplateDefinition
AppmyApp.yaml
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.

Some advantages of using YAML for definitions

Reusing the existing definition

YAML's anchor property and alias indicator make it possible to reuse an already existing definition by referencing it. In the following definition snippet see, for example, the anchor &footerAvailableComponents (line 5) and the alias *footerAvailableComponents (line 14), which allow reusing the components defined in the footer area also in the main area:

  footer:
    inheritance:
      components: all
      enabled: true
    availableComponents: &footerAvailableComponents
      link:
        id: mtk:components/link
      textImage:
        id: mtk:components/textImage
      image:
        id: mtk:components/image
  main:
    availableComponents: # using all components from footer plus others
      <<: *footerAvailableComponents
      html:
        id: mtk:components/html
      linkList:
        id: mtk:components/linkList
      teaser:
        id: mtk:components/teaser
      video:
        id: mtk:components/video
      pageIntro:
        id: mtk:components/pageIntro

The include mechanism

Instead of adding a list item or a value of a map entry you can include a file.

form:
  label: Example page properties
  tabs:
    - name: tabText
      label: Texts and categories
      fields:
        - name: title
          class: info.magnolia.ui.form.field.definition.TextFieldDefinition
          label: Title and categories
          i18n: true
        # an include within a list, here adding a field
        - !include /documentation-examples-templates/dialogs/common/categorization-field.yaml
# an include within a map, here adding a tab
actions: !include /documentation-examples-templates/dialogs/common/actions-block.yaml
   

The !include directive is Magnolia specific. The ! is a special character in YAML for a non-specific tag, see http://www.yaml.org/refcard.html

Path conventions:

  • Absolute path starting with /<module-name>. (This directory within a Maven-based module would be src/main/resources/<module-name>. See Module structure).
  • Same kind of definitions only. The file which includes and the file to be included must be of the same type.
    • (tick) file /my-module/dialogs/mydialog.yaml can include /my-module/dialogs/common-actions.yaml 
    • (tick) file /my-module/dialogs/mydialog.yaml can include /mte/dialogs/default-actions.yaml 
    • (error) file /my-module/dialogs/mydialog.yaml cannot include /my-module/apps/actions.yaml 

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.

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

website.my-page.yaml
'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: 'mtk:pages/basic'

Please note that exporting binary data ( jcr:data: !binary ) into YAML is disallowed in Magnolia 5.5.5+ as this type of export would negatively affect the performance of the snakeyaml parser.

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 

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

Note:

  • The root structure of this file is a mapping.
  • The values of the food and drinks mappings are sequences.
  • The value of the mapping with the key languages is also a mapping.

Further resources about YAML

YAML specification and documentation

Editors supporting YAML syntax

Online YAML tools