designguide theme configyaml
At the center of every Melody theme is its config file, also known as the "config.yaml" file. The config.yaml file is nothing more than a text file that provides an outline of your theme to Melody. It contains everything a theme could possibly need to function, and allows you the designer to create rich user interfaces and experiences to your theme without ever having to program an ounce of code. No PHP, no Perl, no Python, no Ruby, no nothin'.
The term YAML is an acronym for "Yet Another Markup Language" and was designed by humans who recognized the great benefit of markup languages, but had also developed a serious distaste for XML and other forms of markup that seemed great for machines, but horrible for humans.
So if you are even remotely familiar with XML, then the concepts behind YAML should come quite easily to you. For others, YAML can best be summarized as nothing more than a hierarchical syntax for outlining content and data.
Before we begin describing in any detail how Melody themes use YAML, let's give a quick and dirty overview of YAML's syntax -- just enough so that you can feel comfortable reading it and even writing a little of it yourself.
To understand YAML, let's look at a simple XML file, which should be roughly understandable by everyone - even non geeks.
XML
<?xml version="1.0">
<address>
<first_name>Byrne</first_name>
<last_name>Reese</last_name>
<email>byrne@majordojo.com</email>
<company>
<name>Endevver, LLC.</name>
<street_address>
975 Underhills Road, Oakland, CA 94610
</street_address>
</company>
</address>
Pretty straight forward, and self-descriptive as the creators of XML intended. But it is also incredibly verbose, and if the spacing is removed, virtually impossible to read. Now consider the exact same information written in YAML.
YAML
address:
first_name: Byrne
last_name: Reese
email: byrne@majordojo.com
company:
name: Endevver, LLC.
street_address: 975 Underhills Road, Oakland, CA 94610
Aaahhh, it's like a breath of fresh air.
One of the biggest differences between XML and YAML is that in XML spacing does not matter, but in YAML it absolutely does. The up side though is that it forces YAML to be more readable, and for the relationships between one line and the next to be completely unambiguous. Pay close attention to the left alignment of each line and don't use the tab key to achieve it.
And that's about all a designer needs to know about YAML to get started.
A "gotcha" spot with YAML is that to be parsed properly it must end with a new line. Two errors that are common:
-
When trying to move through Melody:
Got an error: Error reading ... Stream does not end with newline character ... -
When building a new theme that currently contains only the very beginnings of metadata, the plugin may show up as
[plugin envelope]/config.yamlwithin the System Information > Installed Plugins screen.
Just add one more empty line to your config.yaml and these problems will disappear!
- Prev: Theme Packaging
- Next: Building Your First Theme
- Table of Contents: MTDG - Theme Designer Guide for Melody
Category: Guide
Tags: theme design
Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.
- Author: Byrne Reese
- Edited by: Violet Bliss Dietz