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

Advanced Fieldset Techniques

These are advanced in the sense that they take slightly more configuration. Advanced functionality, simple implementation.

Extending Fieldsets

Your fieldsets can also include other fieldsets. This becomes useful if you want to reuse a certain combination of fields (for example, meta-data) in multiple fieldsets. To do this, use the include setting at the root level of your fieldset:

fields:
  ## fields you define
include:
  - meta-data

Additionally, you can set multiple fieldsets right in your content fields. This is an advanced solution, as fieldsets are not changeable in the Control Panel (as a measure to preserve your content).

---
title: Bears! Bears Everywhere!
_fieldset:
  - meta
  - main-content

Ordering extended fieldsets

When using include to bring in an another fieldset, the fields are added to the fieldset at the top. You might want to control the order of them amongst the rest of your fields. You can use the field_order to do that. Just create a list of field names.

fields:
  my_field:
    type: text
  another_field:
    type: text
include:
  - extra_fields
field_order:
  - extra_field_1
  - my_field
  - another_field
  - extra_field_2
  - etc

Naming Fieldsets

Your fieldset might need a better name than the filename you’ve chosen. In this situation, just add a title option to your fieldset’s root.

title: Standard Page

Hiding Fieldsets

Sometimes you don’t want to show all fieldsets in your Control Panel (because remember, a content creator can choose from your fieldsets when they click New Page in the Control Panel). For this, you can hide a fieldset from the New Page list with the following:

hide: true