An Introduction to YAML
Author: Manuela Hutter
Introduction
YAML: A data serialization format
Data Types: Scalars
Scalars are simple data types, like strings, integers, boolean values or dates.
Examples:
A simple string
42
true
Data Types: Lists
For exmaple: a list of widgets
- Button
- Edit
- Label
- CheckBox
Data Types: Maps
A map spedifies a bunch of 'key: value' pairs.
For example: the attributes of a button:
name:  MyButton
string: Show
action: Show Mail Panel
icon:   view_icon.png
Nesting Data: List in a Map
Lists and maps can be nested within each other. Here is where indentation comes in: The map value is now not a simple scalar, so it is put in the next line(s) and indented. Indentation is done using spaces. TAB indentation is not allowed.
Example: a layout object holds attributes about itself, plus a list of its child widgets
type: StackLayout
name: main layout
orientation: horizontal
elements:
  - Label
  - Edit
  - Button
Nesting Data: Maps in a List
Also, a list doesn't necessarily just hold strings. A list can again hold nested data.
Example: a list of widgets
- type: Label
  name: name_label
  text: Enter name

- type: Edit
  name: name_edit

- type: Button
  name: save_button
  text: Save
  action: Save Name
Referencing Data
Sometimes you have data that you need to use in different places, and you don't want to copy&paste all content into different places. In YAML, you can set an anchor to a map ('&') in one place, and reference the map ('*') in another place. The anchor is specified in the line above the map.

Example: Use a 'Save' button twice.
- type: Edit
  name: firstname_edit

- &SaveButton
  type: Button
  name: save_button
  text: Save
  action: Save Name

- type: Edit
  name: lastname_edit

- *SaveButton
This example is automatically expanded to:
- type: Edit
  name: firstname_edit

- type: Button
  name: save_button
  text: Save
  action: Save Name

- type: Edit
  name: lastname_edit

- type: Button
  name: save_button
  text: Save
  action: Save Name
Merging Data
Sometimes you need almost the same data in different places, changing just one little thing. You can do this by copying in the map that you want to base your changes on (using '<<'), and then override or add a key/value pair.

Example: Use a 'Save' button twice, but change
its name and add an icon in the second one.
- type: Edit
  name: firstname_edit

- &SaveButton
  type: Button
  name: save_button
  text: Save
  action: Save Name

- type: Edit
  name: lastname_edit

- <<: *SaveButton
  name: save_button_2
  icon: save.png
This example is automatically expanded to:

- type: Edit
  name: firstname_edit

- type: Button
  name: save_button
  text: Save
  action: Save Name

- type: Edit
  name: lastname_edit

- type: Button
  name: save_button_2
  text: Save
  action: Save Name
  icon: save.png
Sample Dialog: Server Name Completion
As found in Tools -> Preferences -> Advanced -> Network -> Server Name Completion

Sample Dialog
dialogs:
  - type: Dialog
    name: Name Completion Dialog
    title: DI_NAMECOMPLETION
    content:
      type: StackLayout
      elements:
        - type: CheckBox
          name: Local_machine_checkbox
          string: DI_IDM_TRY_LOCAL_TOGGLE
        - type: CheckBox
          name: Completion_checkbox
          string: DI_IDM_TRY_NAME_COMPLETION_TOGGLE
          content:
            type: GridLayout
            elements:
              - type: GridRowLayout
                elements:
                  - type: Label
                    name: label_for_Prefixes_edit
                    string: DI_IDM_NC_START_LABEL
                  - type: Edit
                    name: Prefixes_edit
              - type: GridRowLayout
                elements:
                  - type: Label
                    name: label_for_Suffixes_edit
                    string: DI_IDM_NC_END_LABEL
                  - type: Edit
                    name: Suffixes_edit
    button-strip:
      <<: *OkCancelHelpButtonStrip
      help_anchor: "server.html"
definitions:
  buttons:
    OkButton: &OkButton
      type: Button
      name: ok_button
      string: DI_ID_OK
      action: Ok

    CancelButton: &CancelButton
      type: Button
      name: cancel_button
      string: DI_ID_CANCEL
      action: Cancel

    HelpButton: &HelpButton
      type: Button
      name: help_button
      string: DI_ID_HELP
      action: Show help

  button-strips:
    OkCancelHelpButtonStrip: &OkCancelHelpButtonStrip
      type: ButtonStrip
      buttons:
        - *OkButton
        - *CancelButton
        - *HelpButton
References