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

Magnolia YAML files are always combinations of YAML maps and lists. (This said, make sure you understand the concept of these two structures.)

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).

Item	YAML file	Corresponding definition class*
Dialog	`myDialog.yaml`	DialogDefinition
Template	`myTemplate.yaml`	TemplateDefinition
App	`myApp.yaml`	AppDescriptor

* 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 Map2BeanTransformer . Magnolia uses snakeyaml to parse data.

The name property

A definition class often has a property name.

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; }
}

Imagine fooBar is an item within a YAML configuration file.

If fooBar is an entry within a map, the key can be used as the value for the property name. (However it can be overridden.)

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

If fooBar is an item within a list, the name property must be set explicitly.

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

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

Use the Magnolia !include directive to add a reusable YAML chunk. Include a fragment on a sub-level of your definition. Reference the file you include by its resource path starting with /<module-name>/.

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

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.

If you have created the includable fragment after the creation of the file which includes it, save the latter again to force the YAML parser to properly register the definition. /<module-name>/includes is the recommended directory for YAML fragment files. Avoid adding the YAML fragment files into the following directories: apps, blocks, decorations, dialogs, i18n, messageViews, renderers, templates and virtualUriMappings.

With Magnolia 5.5.6+, the !include directive has been extended to provide more functionalities. (See YAML inherit and include).

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:

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

Page tree