Object

Structured object input, which stores properties as YAML.

• Read the guide

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: [e-mail]
  phone: [phone]

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:

Blocks A visual editor for long-form text and modular pages Checkboxes A list of checkbox fields Date A date picker field Email An email input field with validation Files A files select field that allows to select one or multiple related files Gap Layout field to create gaps in the field grid. Headline Creates a headline to group fields Hidden Creates a hidden field Info A plain HTML field for user instructions Layout A visual editor for complex multi-column layouts Line Draws a horizontal line to separate fields List A simple WYSIWYG editor field for ordered and unordered lists Multiselect A select field that allows you to select multiple options Number A number input field with validation Object Structured object input, which stores properties as YAML. Pages A pages select field that allows to select one or multiple related pages Radio A list of radio buttons Range A handy slider Select A simple selectbox field Slug A slug input field Structure Structured data input, which stores data as YAML. Tags An interactive tags input field with autocompletion Tel A phone number input field Text A standard, single-line input field Textarea A textarea field, which auto-resizes and has built-in format buttons. Time A time picker field Toggle Yes/no or on/off toggle Toggles Toggle between different states Url A URL input field with validation Users A user select field that allows to select one or multiple users Writer A simple WYSIWYG editor field for inline content with formats like bold, italic, etc.

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: [e-mail]
      phone: [phone]
    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.