- Available field types
- Field names
- Required fields
- Default values
- Readonly fields
- Field instructions
- Creating grids
- Custom icons
- Translating form fields
- Prevent field values in non-default languages
- Optional field values in non-default languages
Kirby comes with a huge set of custom form fields, which you can use in your blueprints for page and file data. Additionally you can extend Kirby with your own custom fields.
Available field types
Please check out the cheat sheet for a full list of available Panel field types.
In general, you are free to name your fields like you want to, but there are two limitations:
- You can only use alphanumeric characters and underscores in field names.
- If you use field names that are also used by native Kirby methods, your field names will conflict with Kirby's existing methods, e.g. if you give your field a name "image", it will conflict with Kirby's
$page->image()method. You can do this, but you will have to call these fields differently in your templates, for details please refer to the template docs
You can mark fields as required to make sure that your users have to fill in some data before the form gets submitted.
fields: text: label: Text type: textarea required: true
Most fields can have a default value. Default values can be entered as simple text:
fields: street: label: Street type: text default: Sesamestreet 23
To make a field readable but not editable by a user, you can use the
readonly option. This can be useful if you auto-fill fields, either via a hook or a default value.
fields: createdby: label: User type: user readonly: true
Kirby offers multiple ways to validate data, which is stored by users. You can add them to any field of your fields and the form will automatically take care of the validation.
fields: name: label: Name type: text validate: min: 4 max: 140 - alphanum
You can find a list of all available validation methods in the cheat sheet.
Most fields can show a placeholder text when the field is empty. This is a good option to guide users.
fields: street: label: Street type: text placeholder: Please enter a street name… icon: map-marker
Sometimes it is helpful to add some instructions to explain how a field is being used. You can add some helping words by including a
help: line to your field specification in the blueprint, e.g.
fields: name: label: Name type: text validate: min: 4 alphanum help: Minimum of 4 characters required and only alphanumeric characters allowed.
Special characters (e.g.
<) should be added with their character entity reference (e.g.
Form fields can be displayed in a very flexible grid. This is great if you want to save some space in large forms or make it visually easier to scan a form. A perfect example would be an address form.
You can define the width of each field like this:
fields: firstName: label: First Name type: text width: 1/2 lastName: label: Last Name type: text width: 1/2 street: label: Street type: text zip: label: ZIP type: number width: 1/4 location: label: Location type: text width: 3/4
The following column widths are available
If you don't define a column width the field will span the entire width of the form
Most fields can have custom icons, which are set by the
icon parameter. Custom icons can help to make your forms easier to scan.
To define your custom icon, just search for the icon you'd like to add to a field and use its css selector without the
fields: street: label: Street type: text icon: map-marker
Translating form fields
If you have editors from various language backgrounds, you can translate labels, options, headlines and help text for them. You must always provide an English version as a fallback though.
Labels, placeholders and help text
fields: street: label: de: Straße en: Street type: text placeholder: de: Bitte geben Sie einen Straßennamen ein… en: Please enter a street name… help: de: Der Name der Straße en: The name of the street
fields: category: label: en: Category de: Kategorie type: select options: architecture: en: Architecture de: Architektur photography: en: Photography de: Fotografie
fields: headline: label: headline text: de: Optionen en: Options
Prevent field values in non-default languages
Sometimes, you only want to set a value in the default language and prevent changes to the value in all non-default languages. You can do so by setting the
translate option of a field to
false (default is
fields: in_stock: label: In stock type: number translate: false
When set to
false, the field will automatically be made read-only in all non-default languages.
Since Kirby 2.2.3, the contents of an untranslatable field will be emptied in all languages but the default language.
Optional field values in non-default languages
Another possible value for the
translate option is
fields: in_stock: label: In stock type: number translate: optional
The Panel won't pre-fill the field with the value from the default language in this case.
Your templates will still fall back to the default value however. You can use $field->isTranslated($lang = null) to check if that happened.