Using fields

Screencast

Fun with fields

Learn how to create intuitive blueprints for your editors, how to create field layouts, inline help and more.

Naming fields

You can choose the names for your fields freely, but there are two limitations:

You can only use alphanumeric characters and underscores in field names.
Do not use names that are reserved by native page methods. For example, if you give your field the name "image", it will conflict with Kirby's $page->image() method.

You can still use field names that conflict with native page methods. But you will have to call such a field via the $page->content()->image() method. We recommend prefixing your field names instead.

Available fields

If you come from Kirby 2, please note that the title field is automatically added to a page. Please remove all fields called title from your old blueprints.

Conditional fields

In all fields, you can set a condition for displaying the field via the when option. In the when option you define a field name as the key and the required value of that field. In the following example, the text field is only shown when the toggle is set to true:

fields:
  toggle:
    type: toggle
  text:
    type: text
    when:
      toggle: true

If multiple conditions should be fulfilled to show a field, you can add more of them to the when option. All of these conditions need to be fulfilled to display the field:

fields:
  toggle:
    type: toggle
  category:
    type: select
    options:
      - A
      - B
      - C
  text:
    type: text
    when:
      toggle: true
      category: B

Field names still need to be unique, no matter if they are displayed at the same time or not. Values of undisplayed fields will still be preserved and stored in the content file.

Only “and“ conditions are currently possible, so all conditions need to be fulfilled to display the field. For more complicated cases, a third-party plugin is available.

Validating fields

Most fields come with validators you can add as options in your blueprints like min and max etc., or built-in validators like the url field that will automatically check if the given value is a URL. But you can also do more sophisticated validation.

Pattern matches

With the pattern property you can check if the input value matches a given pattern:

text:
  type: text
  pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$'

Using validators

You can also use Kirby's built-in validators or custom validators.

Get a valid IP address:

text:
  type: text
  validate:
    ip

Accept only alphanumerical values:

text:
  type: text
  validate:
    alphanum

Make sure the value starts with a given string:

text:
  type: text
  validate:
    startsWith:
      AB-

Field shortcuts

For simple fields that are only used once per blueprint, you can use a shortcut. Set the field type as key and true as the value:

fields:
  tags: true
  text: true

This code will add a tags field and a text field with their default properties.

These shortcuts can be extended with a label or other field properties, for example:

fields:
  text:
    label: Description
  select:
    options:
      - a
      - b
      - c

Define once, reuse everywhere

If you have field definitions with special settings that you want to use in multiple contexts, you can define them once and reuse them everywhere in your blueprints, see Reusing field definitions.

Custom fields

You can extend this list with your own field types by creating a field plugin.