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.
Such a structure will be stored in the content file like this:
||Optional columns definition to only show selected fields in the structure table.|
||–||Set the default rows for the structure|
||Toggles duplicating rows for the structure|
|empty||–||The placeholder text if no items have been added yet|
||–||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|
||–||The number of entries that will be displayed on a single page. Afterwards pagination kicks in.|
||–||Maximum allowed entries in the structure. Afterwards the "Add" button will be switched off.|
||–||Minimum required entries in the structure|
||–||Toggles adding to the top or bottom of the list|
||–||Sorts the entries by the given field and order (i.e.
||–||Toggles drag & drop sorting|
|when||–||Conditions when the field will be shown (since 3.1.0)|
||The width of the field in the field grid. Available widths:
You can define any number of fields and use the same field types listed:
You can set default values for structure fields which will prepopulate the field:
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.
||Set width of column|
||Set text alignment|
||Set text to prepend value|
||Set text to append value|
||Set visible in mobile view (since v3.6.0)|
Structure columns can be set to any fraction and will be automatically calculated into the right width.
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:
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.
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.
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.
Let's say we wanted to render the
holidays structure field example from above in a template:
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.