Custom form fields

• Getting started
• Anatomy of a field folder
• Accessing data of the current page
• HTML anatomy of a field
• The BaseField class
• The InputField class
• The InputListField class
• Adding field assets

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)

Getting started

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

Anatomy of a field folder

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}Field

Examples

Accessing data of the current page

Just like you can use the $page variable in your templates to access the current page, you can access the page the field belongs to using $this->page() in your field's methods.

HTML anatomy of a field

<!-- 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>

  </div>

  <!-- help -->
  <div class="field-help marginalia text">
    Help text for the field
  </div>

</div>

The BaseField class

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.

The InputField class

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 InputListField class

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.

Adding field assets

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

CSS and JS assets

CSS and JS assets are loaded automatically and must be defined in your field class:

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
    )
  );

  // …

}

/panel/plugins/<field name>/<asset type>/<filename>
e.g.

/panel/plugins/example/images/logo.svg