PHPackages                             plain/kirby-form-block-suite - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. plain/kirby-form-block-suite

ActiveKirby-plugin[Utility & Helpers](/categories/utility)

plain/kirby-form-block-suite
============================

Contactform based on Kirby blocks.

5.1.9(2mo ago)41490↑33.3%14[1 PRs](https://github.com/plain-solutions-gmbh/kirby-form-block-suite/pulls)GPL-3.0-onlyPHPCI passing

Since Dec 12Pushed 2mo ago3 watchersCompare

[ Source](https://github.com/plain-solutions-gmbh/kirby-form-block-suite)[ Packagist](https://packagist.org/packages/plain/kirby-form-block-suite)[ Docs](https://plain-solutions.net/801346)[ RSS](/packages/plain-kirby-form-block-suite/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (53)Used By (0)

Overview
========

[](#overview)

This form plugin for Kirby offers you maximum flexibility and usability. It can be used as a block anywhere you were needed. Even multiple times per page. With the integrated mailview field you can display requests allover the panel.

[![Grid block](./.github/screenshot-grid-form-block.gif)](./.github/screenshot-grid-form-block.gif)

**Packed with a rich set of features:** 🎉

⭐️ Editors can flexibly organize the form fields.

⭐️ Quick form validation without reloading the page (Even during fill in).

⭐️ Incoming requests can be viewed and managed within the block or with the mailview field. (included uploaded files)

⭐️ You and/or the visitors will receive an email on incoming requests.

⭐️ All the default text elements (include mail template) can be changed in the config or in the panel for each form.

⭐️ Multiple forms allowed per page.

⭐️ Templating for outgoing emails.

⭐️ Export forms as CSV (Since 5.1.0).

⭐️ Create a new form field type with ease by added just 2 files (Blueprint & Template).

⭐️ Spam protection with an integrated honeypot.

⭐️ Pre-styled form

⭐️ Full language support for English, German, Italian, French, Lithuanian, Hungarian & Netherlands

Table of content
================

[](#table-of-content)

- [Overview](#overview)
- [Table of content](#table-of-content)
- [Installation](#installation)
- [How to use?](#how-to-use)
    - [Using the built-in styling](#using-the-built-in-styling)
- [Set up your form block](#set-up-your-form-block)
    - [Create a form block](#create-a-form-block)
    - [Set up your form fields](#set-up-your-form-fields)
    - [Define default form block data](#define-default-form-block-data)
    - [Mailview field](#mailview-field)
- [Advanced customizing](#advanced-customizing)
    - [Customize the output](#customize-the-output)
    - [Add a custom form field types](#add-a-custom-form-field-types)
    - [Modify/disable default form field types](#modifydisable-default-form-field-types)
    - [Extend custom fields in form fields](#extend-custom-fields-in-form-fields)
    - [Extend options](#extend-options)
    - [Messages](#messages)
- [Config](#config)
    - [Email address for outgoing emails](#email-address-for-outgoing-emails)
    - [Plain text emails](#plain-text-emails)
    - [Honeypot](#honeypot)
    - [Placeholders](#placeholders)
    - [Disable Functions](#disable-functions)
    - [Email templating](#email-templating)
    - [Translations](#translations)
    - [Dynamic validation](#dynamic-validation)
    - [Email field](#email-field)
    - [Hook Success](#hook-success)
    - [Hook Validate](#hook-validate)
- [Troubleshooting](#troubleshooting)
- [License](#license)

Installation
============

[](#installation)

**Manually**

[Download](https://github.com/plain-solutions-gmbh/kirby-form-block-suite/archive/refs/heads/main.zip) and copy the plugin into your plugin folder: `/site/plugins/`

**With Composer**

`composer require plain/kirby-form-block-suite`

**Get a license**

[Klick here to obtain a license](https://plain-solutions.net/?product=801346)

[See also the other plugins](https://plain-solutions.net/)

**Validate your license**

*Important notes: If you’re working in a development environment, please activate the license on the public domain. Licenses are tied to the domain they are first activated on.*

To validate your license key click on this button:

[![](./.github/license.png)](./.github/license.png)

...or go to *System* in the Panel and click on `plain/formblock` in the Plugins section. (Kirby > 5.0.0). You’ll be guided through the validation process from there.

> If you have trouble with your license, check [Troubleshooting](#troubleshooting) at the end of this documentation.

How to use?
===========

[](#how-to-use)

Just create a block field in your blueprint and add `form` to the fieldsets props:

```
fields:
  my_block:
    type: blocks
    fieldsets:
      - form
```

Then output the block field in your templates with:

```
`
- **`/formfields`**: Here you can find the snippets of each [form field type](#form-field-types). To add a custom formfield following [this instruction](add-a-custom-form-field-types)

> See the comment inside `form.php` for important modification informations.

**Form Object**

The form object provides you a few useful methods that help you to work with the form block: (e.g. `$block->showForm()`)

MethodDescriptionParametershowFormReturns `true` if the form is ready to fill(None)fieldsReturns an array of all form fields.*$attrs:* Array or string of desired attributes (e.g. 'label' returns the title of the field)
(none) returns the **form field object**templatesoutputs a snippet contains in the `snippets/blocks/formtemplates` folder.*$template:* Name of the snippet
*$props:* Array of additional variables you can access with `$props["key_of_your_prop"]`fieldsWithPlaceholderReturns an array of all form field with [placeholders](#placeholders).*$attrs:* Array or string of desired attributes (e.g. 'label' returns the title of the field)
(none) returns the [form field object](#form-field-object)fieldReturns a form field by unique identifier*$slug:* unique identifier of the field
*$attrs:* Array or string of desired attributes (e.g. 'label' returns the title of the field)
(none) returns a [form field object](#form-field-object)attachmentFieldsReturns an array of field slugs with type **file**(none)isFilledReturns `true` if the visitor sends the form(None)isValidReturns `true` if the visitor filled the form correctly(None)isFatalReturns `true` if something went terribly wrong(None)isSuccessReturns `true` if the request was successfully sent(None)errorFieldsReturns as list or array of invalid form fields*$separator:* Char to Separate the field names.
(none) returns an arraymessageReturns a message*$key:* Key of the Text
*$replaceArray:* Assotiative array with additional Placeholder.errorMessageReturns error Message if `isFatal`(None)successMessageReturns success Message if `isSuccess`(None)sendNotification \*Send Email to operator
([if notify enabled](#disable-functions))*$body:* Content of the Email
*$recipient:* Email to send to (optional)sendConfirmation \*Send Email to visitor
([if confirm enabled](#disable-functions))*$body:* Content of the Email
*$reply:* Email that the visitor can answer (optional)setErrorBrings the form to state `isFatal`*$error:* Error message
*$save:* If `true` the request will save in the Inbox> \* Use only if you like to send extra emails. By default, the emails are sent automatically by the plugin after successful completion.

**Form Field Object**

To get the form field object, use `$block->field('slug_of_the_form_field')` or iterate it with `foreach ($form->fields() as $field)`

MethodDescriptionParameter\*Returns the field from the formfield.
 (e.g `$field->custom_field()`)(None)valueValue from form data or default value*$raw*: `true`...
 ...returns the value without HTML escaping
...with Options: returns the slug (not the Label)labelDisplay Name(None)slugUnique identifier(none)filesReturns an array of the files*$key*: Desired attribute of the $\_FILES-Object (name, type, tmp\_name, error, size)
*$item:* Index of the fileautofillContext for autocompletition*$html:*
(none) returns bool
 `attr` returns ' autocomplete="my\_context"'requiredreturn true or expression if field is required*$html:*
(none) returns bool
`asterisk` returns ' \* '
`attr` returns ' required'typeReturns the field type(none)isFilledReturns true if the form field is not empty(none)isValidReturns true if the form field is filled correctly(none)errorMessagesReturns an array of all errors, if invalid.(none)errorMessageReturns one errors, if invalid.(none)hasOptionReturns `true` if the form type is:
checkbox, radio or select(none)selectedOptionsReturns array of selected options*$prop:* Desired property. Default = ValueoptionsReturns a structure field with the options(none)ariaAttrReturns the aria-attribute. (For invalid fields)(none)Add a custom form field types
-----------------------------

[](#add-a-custom-form-field-types)

Let's say you want to create a form field type that shows some information to your visitors:

*site/theme/blueprints/blocks/formfields/info.yml*

```
name: Information
icon: alert

fields:
  title:
    type: text
    width: 1/2
  color:
    type: select
    width: 1/2
    options:
      green: Green
      orange: Orange
      red: Red
  info:
    label: form.block.fromfields.select.placeholder
    type: writer
```

*site/theme/snippets/blocks/formfields/info.php*

```