Structured Field Content

With the syntax for Kirby content files it is very easy to structure any kind of data for your templates. But the latest release of Kirby includes a brand new feature, which will give you even more data-structure-power – the YAML parser.

YAML is a very simple, human-readable structure syntax. It's actually quite similar to the Kirby content syntax and a perfect match. With YAML you will be able to nest structured data inside your content fields. Sounds weird, so let me just show you some examples to demonstrate how it works:

Example: nice addresses

If you are building a contact page and you've got just one address, so far you could simply structure the content like this for example…

Title: Contact
----
Street: 15 Sesamestreet
----
ZIP: 9210
----
City: New York
----
Phone: 500-12131
----
Email: myawesome@email.com

But what happens, when you got more than just one address? Maybe your company has various offices all around the world or you are just very rich and you want to show off with the addresses of your houses on the Bahamas, New York, LA and in Monaco.

One way would be to add subpages for each address and then build a foreach loop with $page->children() to display each address. But that would be quite an oversized solution for just showing more than one address.

You could also add multiple fields like this:

Street_a: 15 Sesamestreet

…

Street_b: 15 Sesamestreet

…

Street_c: 15 Sesamestreet

etc.

but that would be very nasty.

With YAML syntax and the new YAML parser it becomes super easy to add more than just one address in one single field:

Title: Contact
----
Addresses:

Monaco:
  Street: Rue de WTF 17
  ZIP:    1112
  City:   Monaco
  Phone:  555-1234
  Email:  me@monaco.org

New York:
  Street: 1212 Broadway
  ZIP:    4321
  City:   New York
  Phone:  666-4321
  Email:  me@ny.org

Bahamas:
  Street: At the beach
  ZIP:    9999
  City:   The capitol of the Bahamas
  Phone:  777-9999
  Email:  me@bahamas.org

Looks pretty tidy, right? To see the full potential of YAML syntax, check out the YAML site or the YAML Wikipedia entry

How to access data

In your template you can parse YAML like this:

<?php $addresses = yaml($page->addresses()) ?>

This will give you a nice associative array:

Array
(
    [Monaco] => Array
        (
            [Street] => Rue de WTF 17
            [ZIP] => 1112
            [City] => Monaco
            [Phone] => 555-1234
            [Email] => me@monaco.org
        )

    [New York] => Array
        (
            [Street] => 1212 Broadway
            [ZIP] => 4321
            [City] => New York
            [Phone] => 666-4321
            [Email] => me@ny.org
        )

    [Bahamas] => Array
        (
            [Street] => At the beach
            [ZIP] => 9999
            [City] => The capitol of the Bahamas
            [Phone] => 777-9999
            [Email] => me@bahamas.org
        )

)

Hint: Use a::show($array) to inspect the content of any array or object.

You can now use a simple foreach loop to build HTML for all addresses:

<?php foreach($addresses as $address): ?>
<div class="address">

  <?= $address['Street'] ?><br />
  <?= $address['ZIP'] ?> <?= $address['City'] ?>

  …

</div>
<?php endforeach ?>

This works also great in connection with Microformats

More ideas

As you can see this will give you a lot more control and structure for your content. It's not limited to addresses though:

A list of profiles

Title: Elsewhere
----
Profiles:

Twitter:
  Username: bastianallgeier
  Link:     http://twitter.com/bastianallgeier
Zootool:
  Username: bastian
  Link:     http://zootool.com/bastian
Dribbble:
  Username: bastianallgeier
  Link:     http://dribbble.com/bastianallgeier

Your Team Members

Title: Team
----
Team:

Peter:
  Name:    Peter Appleseed
  Email:   peter@peterpaulmary.com
  Phone:   555-1234
  Hobbies: Reading, Writing, Horses, Swimming

Paul:
  Name:    Paul Appleseed
  Email:   paul@peterpaulmary.com
  Phone:   555-1234
  Hobbies: Reading, Writing, Horses, Swimming

Mary:
  Name:    Mary Appleseed
  Email:   mary@peterpaulmary.com
  Phone:   555-1234
  Hobbies: Reading, Writing, Horses, Swimming

…or whatever structured data you need!

I hope this is helpful for you. Let me know how you like it and how you use it or plan to use it for your site.