Structure

Structured data input, which stores data as YAML.

• Read the guide

The structure field makes it possible to add multiple complex entries to a field, which will be stored as YAML. A typical use case would be a list of addresses, team members or a restaurant menu.

Example

fields:
  addresses:
    label: Addresses
    type: structure
    fields:
      street:
        label: Street
        type: text
      zip:
        label: ZIP
        type: text
      city:
        label: City
        type: text

Such a structure will be stored in the content file like this:

addresses:
-
  street: Rue de WTF 17
  zip:    1112
  city:   Monaco
-
  street: 1212 Broadway
  zip:    4321
  city:   New York
-
  street: At the beach
  zip:    9999
  city:   The capitol of the Bahamas

If you need to store a single object instead of a list of objects, take a look at the object field.

Field properties

Name	Type	Default	Description
columns	array	[]	Optional columns definition to only show selected fields in the structure table.
default	array	–	Set the default rows for the structure
disabled	bool	–	If true, the field is no longer editable and will not be saved
duplicate	bool	true	Toggles duplicating rows for the structure
empty		–	The placeholder text if no items have been added yet
fields *	array	–	Fields setup for the structure 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
limit	int	–	The number of entries that will be displayed on a single page. Afterwards pagination kicks in.
max	int	–	Maximum allowed entries in the structure. Afterwards the "Add" button will be switched off.
min	int	–	Minimum required entries in the structure
prepend	bool	–	Toggles adding to the top or bottom of the list
required	bool	–	If true, the field has to be filled in correctly to be saved.
sortBy	string	–	Sorts the entries by the given field and order (i.e. title desc) Drag & drop is disabled in this case
sortable	bool	–	Toggles drag & drop sorting
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 fields with structured data will not be nested inside the same YAML data structure. This ensures broad compatibility.

Default values

You can set default values for structure fields which will prepopulate the field:

fields:
  emails:
    label: Emails
    type: structure
    default:
      - email: [e-mail]
      - email: [e-mail]
      - email: [e-mail]
      - email: [e-mail]
    fields:
      email:
        label: Email
        type: email

Table columns

You can define the columns that are shown in the table. This is especially useful if you have a lot of fields in your structure and you don't want to show them all on first sight, but still keep them editable. Columns can also change the text alignment, set a custom width and define a before and after text that will be prepended or appended to the value.

Option	Value	Description
width	1/2, 1/3, 1/4, 2/3, 3/4 (any fraction since v3.2.0)	Set width of column
align	left, center, right	Set text alignment
before	string	Set text to prepend value
after	string	Set text to append value
mobile	true	Set visible in mobile view (since v3.6.0)

Example

fields:
    holidays:
        type: structure
        columns:
            title:
                width: 1/4
            images:
                width: 1/2
            price:
                width: 1/4
                align: right
                after: "USD"
        fields:
            title:
                type: text
            images:
                type: files
            description:
                type: textarea
            price:
                type: number

Structure columns can be set to any fraction and will be automatically calculated into the right width.

fields:
  mystructure:
    label: Structure
    type: structure
    columns:
      title:
        width: 3/5
      images:
        width: 1/5
      price:
        width: 1/10
    fields:
      title:
        label: A
        type: text
      images:
        label: B
        type: text
      price:
        label: C
        type: text

You can also define columns without additional options if you want to use the defaults. You can still combine this with options for other columns:

fields:
    holidays:
        type: structure
        columns:
            title: true
            images: true
            price:
                align: right
                after: "USD"
        fields:
            title:
                type: text
            images:
                type: files
            description:
                type: textarea
            price:
                type: number

Hide toggle field text in preview

When using toggle fields within structures, displaying the field's text in the preview can sometimes look cluttered. You can hide the text with the text option in the columns' definition.

fields:
  structure:
    columns:
      a:
        text: false
      b:
        text: false
    fields:
      a:
        type: toggle
      b:
        type: toggle
        text: this is some long text

Set columns to visible on mobile

The mobile option keeps cells in responsive views. If none of the columns are set to mobile, only the first column will be visible on mobile.

fields:
  structure:
    columns:
      image:
        type: image
      title:
        type: text
        mobile: true
      date:
        type: date
        mobile: true
    fields:
      image:
        type: files
      title:
        type: text
      date:
        type: date

Preview of fields in the table

The structure field tries to create the best possible preview for the field in its table view. If you are using fields provided by a plugin in the structure field, the preview of these can be customized with a field preview extension.

How to use in templates/snippets

To access a structure field in your templates, you can use the yaml() and toStructure() methods.

Let's say we wanted to render the holidays structure field example from above in a template:

<?php
// using the `toStructure()` method, we create a structure collection
$items = $page->holidays()->toStructure();
// we can then loop through the entries and render the individual fields
foreach ($items as $item): ?>
  <h2><?= $item->title()->html() ?></h2>
  <?php foreach ($item->images()->toFiles() as $image): ?>
    <img src="<?= $image->crop(400)->url() ?>">
  <?php endforeach ?>
  <p><?= $item->price() ?></p>
<?php endforeach ?>

If you nest structure fields inside a structure field, you have to call the toStructure() method on the nested fields as well and then loop through the nested items like above.

More information

Structured field content