🚀 A new era: Kirby 4 Get to know
Skip to content

Structured content

Kirby's content fields can contain any plain text format. But that does not have to be one-dimensional data like a title or some text. One way to further structure plain text is called YAML - a human-readable data structure syntax.

With the help of YAML our content can be even more powerful.

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
ZIP_a: 9210
City_a: New York
Phone_a: 500-12131
Street_b: Rue de WTF 17
ZIP_b: 1112
City_b: Monaco
Phone_b: 555-1234

But that wouldn't be very easy to read and maintain.

With YAML syntax you can add more than just one address in one single field:

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

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

  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 in content fields with the yaml method:

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

This will give you a nice associative array:

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

    [NewYork] => 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 dump($array) to inspect the content of any array or object.


Working with such an array is not difficult, but we can add more Kirby flavor to it, to keep the template syntax more in line with the rest of our APIs.

The toStructure method parses the YAML content and converts it into a nice Kirby-style object.

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

  <?= $address->street() ?><br />
  <?= $address->zip() ?> <?= $address->city() ?>


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

  Username: "@bastianallgeier@mastodon.social"
  Link:     https://mastodon.social/@bastianallgeier
  Username: bastian
  Link:     http://zootool.com/bastian
  Username: bastianallgeier
  Link:     http://dribbble.com/bastianallgeier

Your Team Members

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

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

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

…or whatever structured data you need!