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+
- 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 (
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.)
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.
Maps (also known as dictionaries in YAML) are represented in a simple
form (the colon must be followed by a space):
Combination of Map and List
Let's combine maps and a lists. (It is a common use case in Magnolia YAML files.)
- The "root" structure of this file is a map.
- The value of the map entries with the keys
- The value of the map entry with the key
languagesagain 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*|
* 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
The corresponding YAML file for this template definition would look like this:
YAML data is transformed by Map2BeanTransformer . Magnolia uses snakeyaml to parse data.
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.
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
!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:
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
- http://yaml.org/ (The Official YAML Web Site)
- https://bitbucket.org/asomov/snakeyaml (snakeyaml is the YAML parser used by Magnolia)
- https://code.google.com/p/snakeyaml/wiki/Documentation (snakeyaml documentation)
Editors supporting YAML syntax
- Atom (with plugin)
- Eclipse (with plugin)
- Emacs (with plugin)
- IntelliJ (with plugin)
- Light Table
- Sublime text
- Vim (with plugin by YAML's original author)