This page describes how to use YAML in Magnolia. You can use YAML to define items such as templates, dialogs and apps, and you can import and export content in YAML.

YAML is generally easier to work with than XML. It is easier for humans to read and edit since the content structure is readily visible in YAML. For example, importing multi-line quotes or special characters needs no escaping. YAML is also easier for developers to diff and merge, and the format is more convenient when creating import files from other data sources.

Magnolia uses the SnakeYAML processor to parse YAML. The data is transformed by 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.

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:

/module-a/renderers/json.yaml
!inherit:freemarker
contentType: application/json

The new renderer named json inherits everything from the freemarker renderer but has a different contentType.

Reference a field by its name

Instead of defining the type of a field using the class property, you can reference the type using the fieldType property, which takes the field's short and easy-to-remember alias name as the value.

For example, use fieldType: text instead of class: info.magnolia.ui.form.field.definition.TextFieldDefinition.

To view the field alias names, look in the Definitions app. See also Referencing fields.

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 !include file is not working, check that the first line in the included YAML file does not have any indentation.

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. 


SyntaxRequires versionFunctions
Deprecated syntax. ( (warning) Magnolia 5.5.6+) !include <path/to/a–ressource.yaml>Magnolia 5.4+simple include
New syntax. !include:<path/to/a–ressource.yaml>Magnolia 5.5.6+simple include, include and modify

Example:

/module-a/dialogs/components/lazy-component.yaml
form:
  label: lazy-component
  tabs:
    # an include within a list, here adding a complete tab
    - !include:/module-a/includes/categorization-tab.yaml
      label: Yo! 1-tab-only!
      fields:
        # modify properties of the field blackOrWhite which comes from the include
        - name: blackOrWhite
          label: Choose color
# an include within a map, here adding the actions for the root (map) item "actions"
actions: !include:/module-a/includes/common-actions.yaml
  # add another action to those which already exist from the include
  doit:
    label: Same as cancel
    class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition

  • Line 6: Modify the label of the included tab.
  • Lines 9 and 10: Modify the label of the blackOrWhite field from the include.
  • Lines 14 to 16: Add another action to the imported actions.

For more information read YAML inherit and include.

YAML override

Use !override to completely ignore the properties of an inherited or included node. As a consequence, you have to add specify properties to the given node.

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 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:

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

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'

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

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


#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))