Fields
No matter if you use presets or create your own layouts, form fields are an essential part of the configuration and have very powerful options.
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.
Available form fields
Checkboxes
A list of checkbox fields
Date
A date picker field
An email input field with validation
Files
A files select field that allows to select one or multiple related files
Headline
Creates a headline to group fields
Hidden
Creates a hidden field
Info
A plain HTML field for user instructions
Line
Draws a horizontal line to separate fields
Multiselect
A select field that allows you to select multiple options
Number
A number input field with validation
Pages
A pages select field that allows to select one or multiple related pages
Radio
A list of radio buttons
Range
A handy slider
Select
A simple selectbox field
Structure
Structured data input, which stores data in a field as YAML.
Tags
An interactive tags input field with autocompletion
Tel
A phone number input field
Text
A standard, single-line input field
Textarea
A textarea field, which auto-resizes and has built-in format buttons.
Time
A time picker field
Toggle
Yes/no or on/off toggle
Url
A URL input field with validation
Users
A user select field that allows to select one or multiple users
Conditional fields
3.1.0
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
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
Custom fields
You can extend this list with your own field types by creating a field plugin.