Structured field content
Add structured data like addresses, events, etc. to your site.
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.
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: firstname.lastname@example.org
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:
Monaco: Street: Rue de WTF 17 ZIP: 1112 City: Monaco Phone: 555-1234 Email: email@example.com NewYork: Street: 1212 Broadway ZIP: 4321 City: New York Phone: 666-4321 Email: firstname.lastname@example.org Bahamas: Street: At the beach ZIP: 9999 City: The capitol of the Bahamas Phone: 777-9999 Email: email@example.com
In your template you can parse YAML in content fields with the
<?php $addresses = $page->addresses()->yaml() ?>
This will give you a nice associative array:
Array ( [Monaco] => Array ( [Street] => Rue de WTF 17 [ZIP] => 1112 [City] => Monaco [Phone] => 555-1234 [Email] => firstname.lastname@example.org ) [NewYork] => Array ( [Street] => 1212 Broadway [ZIP] => 4321 [City] => New York [Phone] => 666-4321 [Email] => email@example.com ) [Bahamas] => Array ( [Street] => At the beach [ZIP] => 9999 [City] => The capitol of the Bahamas [Phone] => 777-9999 [Email] => firstname.lastname@example.org ) )
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.
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() ?> … </div> <?php endforeach ?>
This works also great in connection with Microformats
As you can see this will give you a lot more control and structure for your content. It's not limited to addresses though:
Twitter: Username: bastianallgeier Link: http://twitter.com/bastianallgeier Zootool: Username: bastian Link: http://zootool.com/bastian Dribbble: Username: bastianallgeier Link: http://dribbble.com/bastianallgeier
Peter: Name: Peter Appleseed Email: email@example.com Phone: 555-1234 Hobbies: Reading, Writing, Horses, Swimming Paul: Name: Paul Appleseed Email: firstname.lastname@example.org Phone: 555-1234 Hobbies: Reading, Writing, Horses, Swimming Mary: Name: Mary Appleseed Email: email@example.com Phone: 555-1234 Hobbies: Reading, Writing, Horses, Swimming
…or whatever structured data you need!