YAML

This page is about using YAML in Magnolia. YAML is a data serialization format designed for human readability and interaction with scripting languages. Use YAML to configure and define apps, dialogs, field types, message views and templates, media editor and renderers. You can define these same items using JCR nodes via Configuration app; YAML is just an additional possibility.  Magnolia 5.4+ 

Syntax

• 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 (').

For a complete reference of the YAML syntax please check up http://yaml.org/ or http://www.yaml.org/refcard.html.

Lists and Maps

Lists

Members of a list are lines beginning at the same indentation level starting with leading hyphen (dash) and at least one space ( -  ). The number of spaces after the leading hyphen must be the same for all list members.

# A list of food
- Sandwich
- Pizza
- Burrito
- Chocolate cake

Maps

Maps (also known as dictionaries in YAML) 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 

Combination of Map and List

Let's combine maps and a lists. (It 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] # drinks is another example of another notation of a list
languages:
    groovy: Beginner
    java: Beginner
    freeMarker: Expert

Note:

• The "root" structure of this file is a map.
• The value of the map entries with the keys food and drinks are lists
• The value of the map entry with the key languages again is a map

YAML in the context of Magnolia

YAML data is transformed to definition classes

YAML files are meant to configure or define "items" like app, templates and dialogs. In a running system the data written in YAML is represented by a Java Bean. Below you find a table of Magnolia YAML files and their corresponding Magnolia classes (usually called definition or description class). 

* You also can use custom definition classes (which usually extend the classes mentioned above). In that case you must provide the class as an attribute in the YAML file.

Example: Using custom definition classes

Imagine you have your own template definition class com.example.magnolia.templates.CustomTemplateDefinition. 

package com.example.magnolia.templates;
 
public interface CustomTemplateDefinition extends TemplateDefinition{
	String getBodyClass;
}

The corresponding YAML file for this template definition would look like this:

class: com.example.magnolia.templates.CustomTemplateDefinition
renderType: freemarker
templateScript: /example-project/templates/pages/defaultTemplate.ftl
title: Default template
visible: true     
bodyClass: default-layout       

YAML data is transformed by 

public class FooBarDefinition {
    private String name;
    private boolean abc;
    private boolean xyz;

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public boolean getAbc() { return abc; }
    public void setAbc(boolean abc) { this.abc = abc; }
    public boolean getXyz() { return xyz; }
    public void setXyz(boolean xyz) { this.xyz = xyz; }
}

employee:
  skills:
  	programming:
      java: good
      ftl: excellent
    miscellaneous: # here the item miscellaneous is a map
      musical: False
      fooBar:
        # name: offBar (the property 'name' can be set. If not, the key is used!)
        abc: True
        xyz: False

employee:
  skills:
    programming:
      java: good
      ftl: excellent
    miscellaneous: # here the item miscellaneous is a list
      - musical: False
      - fooBar
          name: fooBar
          abc: True
          xyz: True

Differences between YAML file and JCR node based configuration data

YAML configuration has some benefits and disadvantages over JCR node based configuration. See Configuring in JCR vs YAML.

Include mechanism 

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/includes/categorization-field.yaml
# an include within a map, here adding a tab
actions: !include /documentation-examples-templates/includes/default-actions-block.yaml
   

Exporting JCR configuration to YAML

You can export JCR data from the config workspace to YAML. This is useful for moving from repository-based configuration to file-based configuration.

YAML export is only available for definition items:

• Template definitions
• Dialog definitions
• Message view definitions
• FieldTypes
• MediaEditors
• Renderers
• Apps

The Export to YAML action is disabled for other items.

When using YAML files originating from export, you might have to change the file name if you want to use it within a module; for instance the name of the YAML file defining an app must reflect the app name with the pattern <app-name>.yaml.

Resources

Links

• http://yaml.org/ (The Official YAML Web Site)
• http://yaml.org/spec/
• http://www.yaml.org/refcard.html
• https://bitbucket.org/asomov/snakeyaml (snakeyaml is the YAML parser used by Magnolia)
• https://code.google.com/p/snakeyaml/wiki/Documentation (snakeyaml documentation)
• http://en.wikipedia.org/wiki/YAML 
• http://docs.ansible.com/YAMLSyntax.html

Editors supporting YAML syntax

• Atom (with plugin)
• Brackets
• Eclipse (with plugin)
• Emacs (with plugin)
• IntelliJ (with plugin)
• Light Table
• Sublime text
• Vim (with plugin by YAML's original author)

Online YAML parser

• http://yaml-online-parser.appspot.com/
• http://codebeautify.org/yaml-validator