Fields & Fieldsets
Defining the fields you wish to use per folder.
Statamic lets you define fields in arrangements called fieldsets. You then tell Statamic which content uses which fieldset, and the Control Panel builds out the appropriate form for you.
Fieldsets
A fieldset is a simple YAML file that defines a list of fields.
Your fieldsets are kept in the _config/fieldsets
folder.
A fieldset file consists of a single top-level key (fields
), and allows you to set and configure any number of content fields utilizing any combination of the available fieldtypes.
An example of what a fieldset might look like:
fields:
description: ## the template tag, i.e. {{ description }}
display: Description ## the Control Panel field label (optional)
required: false ## true/false for validation (optional)
default: ## default value (optional)
type: redactor ## fieldtype (optional, text by default)
instructions: Write! ## instructional text
author:
display: Author
required: true
default: Bear Grylls
type: users
Naming Fields
You can name your fields any way you choose but each field name needs to be unique and you can not use a hyphen to separate names, underscores are allowed.
Instructions
You can add instructions to your field by adding a string to instructions
like in the example above. If you need text above and/or below, you can be explicit and add both of these yourself.
instructions:
above: This text goes above
below: This text goes below
You can also add line breaks by using a pipe |
character.
instructions: |
These instructions
are on two lines
Using Fieldsets
To assign a fieldset to a piece of content, use the _fieldset
setting in your front matter.
For example, want a page to use the fieldset located in _config/fieldsets/page.yaml
?
Add this to the front matter:
_fieldset: page
Additionally, you may use the Fieldset selector in the Control Panel by simply clicking New Page in the Pages view.
Fieldsets for Entries
Entries are unique in that they consist of an entire folder full of similarly structured content files, all sharing the same fields and defaults.
In order to make a fieldset globally available for an entire Entry type, you place a fields.yaml
file into the folder with either the desired fieldtype to use, or a one-off fields configuration.
In other words, you can set your fieldset right on the spot, or re-use any set you’ve created already.
Entry Type
There are currently two types of entries: date and number. Date entries are date-based, with URLs beginning with a year-month-day datestamp (e.g. 2013-07-04-fireworks.md
).
Number entries are entries that begin with a numeral, used to optionally indicate their manual sort order in any given listing.
To determine the ordering mechanism for a folder’s entries, set the type
setting in that folder’s fields.yaml
.
type: date|number