🚀 A new era: Kirby 4 Get to know
Skip to content

Fields

Content within text files can be structured with fields. You can add as many fields to a content file as your content model requires. Each text file can contain its very own set of fields. Together with the flexible folder structure you get a NoSQL-like data store with literally unlimited possibilities.

Adding fields manually

If you prefer to write your content files in a text editor, you can separate one field from the next with four dashes on a separate line:

Title: An interesting article
----
Date: 2024-03-18
----
Text:

Really interesting content here...

Each field begins with the fieldname and a colon. The content of a field can be a single or multiple lines of text. You can store plain text, HTML, JSON, YAML or anything else which can be written in plain text in a field.

Fields can be added or removed at any time. All fields are instantly available in Kirby's templates.

When you add fields manually, there is no way to validate what you enter into each field.

Fields in the Panel

Before fields are available to be filled by users in the Panel, they need to be defined for each content model. These field definitions are done in blueprints and give you full control over what sort of content each field can contain.

The Panel comes with many pre-defined field types that help with structuring your content. A full list of available field types and their options can be accessed in the Reference:

There are several plugins with custom field types available.

Naming fields

In general, you are free to name your fields freely, but there are some limitations:

  1. You can only use alphanumeric characters (a-z, A-Z, 0-9) and underscores in field names, so no dashes or special characters.
  2. Field names may conflict with Kirby's native methods. If you name a field image for example, it will conflict with the native $page->image() method.
  3. You may not use a field named title directly in a page blueprint, unless it is nested within another field (structure field, object field, blocks field).

To be on the safe side with your field names, you have two options:

  1. Always prefix your field names, for example with your initials: xy_myfieldName.
  2. Render your field names in your templates via the content object, i.e. instead of the shortcut $page->myFieldName() use `$page->content()->get('myFieldName'), compare Accessing fields in templates below.

For details see also  the template docs.

Accessing fields in templates

Field content is accessible in your templates via the field's name:

<?= $page->title()->html() ?>
<?= $page->text()->kirbytext() ?>
<?= $page->date()->toDate('Y-m-d') ?>

The methods that are chained to the name of the field are field methods that allow you to modify the field content in multiple ways. You can find a full list of available field methods in the Reference.

Some technical background: Fields are part of the Content object which is returned when calling $page->content(), so the longer, standard way of accessing a field would be:

<?= $page->content()->get('title') ?>

However, Kirby uses the magic __call method in the Page class to resolve these shortcuts via the field name, as shown above. This magic methods makes sure that native methods always take precedence over your content field names to make sure Kirby works as expected. And this is also the reason why conflicting field names will not work with these shortcuts.