README

A flexible form builder and handler based on Kirby's layout und block fields and Kirby Uniform.

Features

🎨 Form builder using Kirby's built-in layout and blocks fields
🔒 Form handling using Kirby Uniform
✔️ Client-side and server-side validation
📋 View entries directly in the panel
📬 Send confirmation and notification emails
🔗 Use Post/Redirect/Get pattern to avoid multiple submission

Demo

kirby-forms-demo.mp4

Installation

Make sure you have Kirby Uniform installed, then install the plugin using Composer:

composer require arnoson/kirby-forms

Getting started

The quickest way to get started is creating a new page with the form blueprint provided by the plugin. Now you can build your form in the panel. To render the form, use the form snippet inside your template:

snippet('form');

Options

Most options can be configured per form in the Panel:

These global options can only be set in the plugin's config:

'arnoson.kirby-forms' => [
  // A list of email addresses that can be selected in the panel as the sender
  // of confirmation and notification emails.
  'fromEmails' => [],

  // Wether or not to use client validation (in addition to server-side
  // validation done by Kirby Uniform).
  'clientValidation' => true,

  // How many columns to use for the grid that determines the layout of the
  // form. see: https://getkirby.com/docs/reference/panel/fields/layout#calculate-the-column-span-value
  'gridColumns' => 12,

  // Wether or not to use the `autocomplete` attribute for the form element.
  'autoComplete' => false,

  // Wether ot not to render the previous values in the form (e.g.: in the case
  // a form submit wasn't successful and the form is shown again to the user)
  'showOldValues' => true,
]

Entries

Form entries will be saved directly in the form page and can be viewed/deleted/edited in the panel:

Using Different Layouts

By creating your own fields/form-fields blueprint, you can overwrite the possible layouts in the form builder. Use this file as a starting point.

Adding Custom Fields

The easiest way to add your own custom fields is to start with the example.

Custom fields consist of

A block blueprint (defining the field settings like required, min, max, ...)
A block snippet (to render the fields on the form)

The block name must follow the naming convention of form-field-<panel-field-name>, where <panel-field-name> is a panel field, used to render the field's value in the Entries view.

Ideally, a custom field should also have a block preview.

To show your custom field as an option in the Kirby Forms form builder, you have to override the fields/form-fields blueprint, see the example.

Contribute

Contributions to the plugin and it's documentation are welcome :~) Please make sure you:

use prettier to format your code (should happen automatically if you work on this project in VSCode)
use conventional commits (these are used to automatically generate release messages, including credits for your contributions)

To get started have a look at the package.json.

arnoson / kirby-forms

Maintainers

Details