Object

The object field allows to create data objects. This is handy for more complex settings, isolated entities or nested data.

A typical example would be contact data for an author in a blog article, multiple layout settings for images in your template, custom settings for a theme, SEO configuration etc.

Example

fields:
  contact:
    type: object
    fields:
      photo:
        type: files
      name:
        type: text
      email:
        type: email
      phone:
        type: tel

Such an object will be stored in the content file like this:

contact:
  photo:
    - file://hb38HvnQfm8HlQ6e
  name: Nandi Peters
  email: nandi@example.com
  phone: 1234 5678

If you need to store a list of multiple objects, take a look at the structure field.

Field properties

Name	Type	Default	Description
default		–	Set the default values for the object
disabled	`bool`	–	If `true`, the field is no longer editable and will not be saved
empty		–	The placeholder text if no information has been added yet
fields	`array`	`[]`	Fields setup for the object form. Works just like fields in regular forms.
help		–	Optional help text below the field
label		–	The field label can be set as string or associative array with translations
required	`bool`	–	If `true`, the field has to be filled in correctly to be saved.
translate	`bool`	`true`	If `false`, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
when		–	Conditions when the field will be shown (since 3.1.0)
width	`string`	`1/1`	The width of the field in the field grid. Available widths: `1/1`, `1/2`, `1/3`, `1/4`, `2/3`, `3/4`

Fields

You can define any number of fields and use the same field types listed:

Each field value is stored like in a normal Kirby content file. This means that all field types are supported, however all of their values are converted to strings. For most fields there is no difference, but structured fields will not be nested inside the same YAML data structure. This ensures broad compatibility.

Default values

You can set default values for an object field which will prepopulate the field when a new page is created.

fields:
  contact:
    type: object
    default:
      name: Nandi Peters
      email: nandi@example.com
      phone: 1234 5678
    fields:
      photo:
        type: files
      name:
        type: text
      email:
        type: email
      phone:
        type: tel

How to use in templates/snippets

To access a object field in your templates, you can use the toObject() method.

Let's say we wanted to render the contact data from above in a template:

<?php if ($contact = $page->contact()->toObject()): ?>
<dl>
  <dt>Photo</dt>
  <dd><?= $contact->photo()?->toFile()->crop(200) ?></dd>
  <dt>Name</dt>
  <dd><?= $contact->name() ?></dd>
  <dt>Email</dt>
  <dd><?= $contact->email() ?></dd>
  <dt>Phone</dt>
  <dd><?= $contact->phone() ?></dd>
</dl>
<?php endif ?>

If you nest object fields inside another object field, block field or structure field, you have to call the toObject() method on the nested fields as well and then access the nested object properties like above.