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
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.
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.
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
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:
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.
Most fields come with validators you can add as options in your blueprints like
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 property you can check if the input value matches a given pattern:
Get a valid IP address:
Accept only alphanumerical values:
Make sure the value starts with a given string:
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:
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:
You can extend this list with your own field types by creating a field plugin.