Learn how to create your own form fields for the panel.
Kirby comes with a big set of predefined form field types, but you will probably want to extend this set sooner or later. Creating your own form fields is very simple and yet you have the freedom to come up with very complex fields if you need to (the structure field is such a complex example)
All custom fields go into the /site/fields
folder. Each field gets its own subfolder. The name of the subfolder determins the name, which is going to be used in the type:
option. You can not only create new fields in /site/fields
but also overwrite existing fields by using an existing name (i.e. text)
The best way to get started is to copy an existing field, which is closest to what you are going to build. Native fields are located in /panel/app/fields
. Never work directly on native fields. All your changes will be destroyed with the next update
There's one file which must be present in a field folder and it must be named like this:
/site/fields/{fieldname}/{fieldname}.php
This file must contain a class following the class name convention for fields:
{Fieldname}Class
Field name | file | class |
---|---|---|
text | /site/fields/text/text.php | class TextField {} |
phone | /site/fields/phone/phone.php | class PhoneField {} |
url | /site/fields/url/url.php | class UrlField {} |
<!-- template -->
<div class="field field-grid-item field-with-icon">
<!-- label -->
<label class="label" for="form-field-title">
Title <abbr title="Required">*</abbr>
</label>
<!-- content -->
<div class="field-content">
<!-- input -->
<input class="input" required="true" name="title" id="form-field-title" type="title" value="About">
<!-- icon -->
<div class="field-icon">
<i class="icon fa fa-font"></i>
</div>
<!-- help -->
<div class="field-help marginalia text">
Help text for the field
</div>
</div>
</div>
The BaseField class is the foundation for all fields. It defines the basic methods and attributes that fields have. If you want to create a field from scratch you probably want to check out and extend this class.
class ExampleField extends BaseField {
// your custom field stuff goes here
}
Find the BaseField class on Github.
If you want to create a customized input field (text input, number input, url input, etc.) the InputField class is a good template to start with. It's an extension of the BaseField class and thus inherits all methods and attributes.
class ExampleField extends InputField {
// your custom field stuff goes here
}
Find the InputField class on Github.
The checkboxes and radiobuttons fields are special, because they are a list of fields. If you want to create a similar list you can extend their underlying InputListField class.
class ExampleField extends InputListField {
// your custom field stuff goes here
}
Find the InputListField class on Github.
A field can have additional assets located in an assets
subfolder. The recommended structure for the assets folder is…
/site/fields/{fieldname}/assets/
/site/fields/{fieldname}/assets/css
/site/fields/{fieldname}/assets/js
/site/fields/{fieldname}/assets/images
/site/fields/{fieldname}/assets/fonts
Assets must be defined in your field class to be loaded correctly.
class ExampleField extends BaseField {
static public $assets = array(
'js' => array(
'script-a.js', // /path/to/field/assets/js/script-a.js
'script-b.js', // /path/to/field/assets/js/script-b.js
),
'css' => array(
'styles.css' // /path/to/field/assets/css/styles.css
)
);
// …
}