Reference

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

Options

Option	Type	Required	Default	Description
columns	array		[]	Optional columns definition to only show selected fields in the structure table.
default	mixed			Default value for the field, which will be used when a Page/File/User is created
disabled	bool			If true, the field is no longer editable and will not be saved
fields	array	required		Fields setup for the structure form. Works just like fields in regular forms.
help	mixed			Optional help text below the field
label	mixed			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
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.
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.

Default values

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

emails:
    label: Emails
    type: structure
    default:
      - email: bastian@getkirby.com
      - email: lukas@getkirby.com
      - email: nico@getkirby.com
      - email: sonja@getkirby.com
    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.

Example

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

Accessing structure fields in your templates

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

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.