A flexible form builder and handler based on Kirby's layout and block fields and [Kirby Uniform](https://github.com/mzur/kirby-uniform/).
## Features
- 🎨 Form builder using Kirby's built-in layout and blocks fields
- 🔒 Form handling using [Kirby Uniform](https://github.com/mzur/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
https://github.com/user-attachments/assets/4c02de74-31c4-4b89-8444-39b5c0e5d6bb
## Installation
Make sure you have [Kirby Uniform](https://github.com/mzur/kirby-uniform/) installed, then install the plugin using Composer:
```shell
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:
```php
snippet('form');
```
## Options
Most options (success message, confirmation emails, ...) can be configured per form direcly in the panel in the form's `Settings` tab.
These global options can only be set in the plugin's config:
```php
'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,
]
```
## 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](https://github.com/arnoson/kirby-forms/blob/master/blueprints/fields/form-fields.yml) as a starting point.
## Adding Custom Fields
The easiest way to add your own custom fields is to start with the [example](https://github.com/arnoson/kirby-forms/tree/master/example/site/plugins/custom-form-fields).
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-`, where `` is a [panel field](https://getkirby.com/docs/reference/panel/fields), used to render the field's value in the [Entries](#entries) view.
Ideally, a custom field should also have a [block preview](https://getkirby.com/docs/cookbook/panel/custom-block-type#simple-index-js).
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](https://github.com/arnoson/kirby-forms/tree/master/example/site/blueprints/fields/form-fields.yml).
## 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](https://www.conventionalcommits.org) (these are used to automatically generate release messages, including credits for your contributions)
To get started have a look at the `package.json`.
