DreamForm

https://plugins.andkindness.com/dreamform/docs
Admin
DreamForm is an opinionated form builder plugin for Kirby CMS 4+ that enables users to create single...
Tokens:11,078
Snippets:66
Trust Score:5.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start PHP Development Server with Composer

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/demo

Initiates the PHP development server, making the DreamForm site accessible in your web browser at `http://localhost:8000`. Before starting, ensure you have copied `.env.example` to `.env` and added a secret for HTMX encryption.

```bash
composer start
```

--------------------------------

### Install Kirby DreamForm with Composer

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/installation

This Composer command is the recommended way to install the Kirby DreamForm plugin. Executing this in your project's terminal will download and integrate the plugin into your Kirby installation, streamlining the setup process.

```Shell
composer require tobimori/kirby-dreamform
```

--------------------------------

### Install Kirby and DreamForm Dependencies with Composer

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/demo

Installs all required PHP dependencies, including Kirby 4, DreamForm, and other utility plugins like DotEnv and Ray, using Composer. Ensure Composer is installed on your system before running this command.

```bash
composer install
```

--------------------------------

### DreamForm Manual Installation: Create forms.txt

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/installation

Manually set up the forms folder and create `forms.txt` (or language-specific variant) within your site's `content` directory. Add the specified Uuid content to this file to register the forms.

```plain
Uuid: forms
```

--------------------------------

### Clone DreamForm Plainkit Repository

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/demo

Clones the DreamForm Plainkit repository from GitHub into a new directory named 'df-plainkit' and then changes the current working directory into it. This is the first step to get the project files.

```bash
git clone https://github.com/tobimori/dreamform-plainkit df-plainkit && cd df-plainkit
```

--------------------------------

### DreamForm Encryption Secret Configuration (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/installation

Configure the encryption secret in `site/config/config.php` for HTMX or API submissions. It's crucial to load this secret from an environment variable (e.g., using `kirby-dotenv`) for security, preventing it from being committed to your repository.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    // encryption secret for htmx attributes
    'secret' => fn () => env('DREAMFORM_SECRET')
  ],
];
```

--------------------------------

### Add DreamForm to Kirby Panel Sidebar Menu (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/installation

Integrate the 'Forms' entry into the Kirby Panel sidebar menu by modifying `site/config/config.php`. Utilize the provided `Menu` helper class from the DreamForm plugin to easily add the forms section alongside other panel entries.

```php
// site/config/config.php

use tobimori\DreamForm\Support\Menu;

return [
  // Custom menu to show forms in the panel sidebar
  'panel.menu' => fn () => [
    'site' => Menu::site(),
    'forms' => Menu::forms(),
    'users',
    'system',
    // [...]
  ],
];
```

--------------------------------

### Define Default Page Blueprint with DreamForm Field

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/demo

This YAML snippet from `/site/blueprints/pages/default.yml` defines the blueprint for a default page. It includes a `dreamform/fields/form` panel field, allowing content editors to select a specific form which will then be rendered by the corresponding page template.

```yaml
title: Default Page

columns:
  main:
    width: 2/3
    sections:
      fields:
        type: fields
        fields:
          text:
            toolbar:
              inline: false
            type: writer
            inline: true
          form: dreamform/fields/form
  sidebar:
    width: 1/3
    sections:
      pages:
        type: pages
        template: default
      files:
        type: files
```

--------------------------------

### Generate DreamForm Encryption Secret (OpenSSL)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/installation

Use the OpenSSL command-line tool to generate a strong, random 32-byte base64 encoded secret. This generated string can be used as the `DREAMFORM_SECRET` environment variable for plugin encryption.

```bash
openssl rand -base64 32
```

--------------------------------

### Define Kirby Plugin for Calculation Guard

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

This snippet shows how to define a basic Kirby plugin. Create a folder `calc-guard` in `site/plugins` and an `index.php` file within it. This setup allows Kirby to autoload the plugin and its components, making the guard available across projects.

```php
// site/plugins/calc-guard/index.php

use Kirby\Cms\App as Kirby;

Kirby::plugin('tobimori/calc-guard', []);
```

--------------------------------

### Render DreamForm in Default PHP Template

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/demo

This PHP snippet from `/site/templates/default.php` demonstrates how to render a selected DreamForm using the `dreamform/form` snippet. It includes extensive attribute customization for various form elements (rows, fields, labels, inputs, buttons, errors, radios, checkboxes, files) by applying Tailwind CSS classes.

```php
<?php
    /* Render the form selected in the page */
    snippet('dreamform/form', [
      'form' => $page->form()->toPage(),
      'attr' => [
        'row' => ['class' => 'gap-4 mb-4'],
        'field' => ['class' => 'group flex flex-col items-start mb-4 last:mb-0'],
        'label' => ['class' => 'text-sm font-medium text-slate-600 mb-1'],
        'input' => ['class' => 'peer group-data-[has-error]:placeholder-shown:mb-2 shadow-sm group-data-[has-error]:placeholder-shown:border-red-500 w-full border border-gray-200 rounded p-2'],
        'button' => ['class' => 'ml-auto bg-indigo-600 text-white py-2 px-4 rounded shadow-sm hover:bg-indigo-800 transition-colors duration-200'],
        'error' => ['class' => 'peer-[:not(:placeholder-shown)]:hidden text-red-500 text-sm'],
        'radio' => [
          'label' => ['class' => 'text-sm font-medium text-slate-600 mb-2'],
          'input' => ['class' => 'w-4 rounded-full mr-2 shadow-sm border border-gray-200 '],
          'error' => ['class' => 'group-has-[:checked]:hidden text-red-500 text-sm'],
          'row' => ['class' => 'flex items-center mb-1 text-sm']
        ],
        'checkbox' =>  [
          'label' => ['class' => 'text-sm font-medium text-slate-600 mb-2'],
          'input' => ['class' => 'w-4 mr-2 shadow-sm border border-gray-200 rounded'],
          'error' => ['class' => 'group-has-[:checked]:hidden text-red-500 text-sm'],
          'row' => ['class' => 'flex items-center mb-1 text-sm']
        ],
        'file' => [
          'input' => ['class' => 'mt-1 w-full border border-gray-200 group-data-[has-error]:mb-2 group-data-[has-error]:border-red-500 text-gray-600 shadow-sm rounded file:cursor-pointer file:transition-colors file:bg-gray-100 file:border-0 file:mr-3 file:py-2 file:px-4 file:hover:bg-gray-200'],
          'row' => ['class' => 'flex items-center mb-1 text-sm']
        }
      ]
    ]); ?>
```

--------------------------------

### Configure Editor User Permissions for DreamForm

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/demo

This YAML snippet from `/site/blueprints/users/editor.yml` sets specific DreamForm permissions for the editor role. It explicitly denies editors the ability to create or update forms (`"*": false`) but grants them access to view existing forms and submissions (`accessForms: true`, `accessSubmissions: true`).

```yaml
title: Editor
permissions:
  tobimori.dreamform:
    "*": false
    accessForms: true
    accessSubmissions: true
```

--------------------------------

### Default HTML Structure of Dreamform Generated Form

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/styling

This HTML snippet illustrates the simplified default structure of a form generated by the Dreamform plugin. It shows how elements like <form>, <error>, <row>, <column>, <field>, <label>, <input>, <textarea>, <select>, and <button> are nested, including examples of error indicators and different input types. This structure can be partially overridden by customizing plugin snippets.

```html
<form>
	<error data-error="true">
	<row>
		<column style="grid: half;">
			<field data-has-error>
				<label>
				<input>
				<error data-error="key">
			</field>
			<field>
				<label>
				<textarea>
				<error data-error="key">
			</field>
		</column>
		<column style="grid: half;">
			<field>
				<label>
				<select>
				<error data-error="key">
			</field>
			<field>
				<row>
					<input type="radio">
					<label>
				</row>
				<row>
					<input type="radio">
					<label>
				</row>
				<row>
					<input type="radio">
					<label>
				</row>
				<error data-error="key">
			</field>
		</column>
	</row>
	<row>
		<column style="grid: full;">
			<field>
				<button>
			</field>
		</column>
	</row>
</form>
```

--------------------------------

### Akismet Guard Configuration Options Reference

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/akismet

This section provides a detailed reference for all configurable options available for the `tobimori.dreamform.guards.akismet` guard. It includes default values, accepted data types, and a description for each parameter, allowing fine-grained control over Akismet integration.

```APIDOC
tobimori.dreamform.guards.akismet:
  apiKey:
    Default: null
    Accepts: string|callback
    Description: The Akismet API key from your account page
  fields.comment_author:
    Default: [...]
    Accepts: array
    Description: Fields to use for the author name param
  fields.comment_author_email:
    Default: [...]
    Accepts: array
    Description: Fields to use for the email param
  fields.comment_author_url:
    Default: [...]
    Accepts: array
    Description: Fields to use for the url/website param
  fields.comment_content:
    Default: [...]
    Accepts: array
    Description: Fields to use for the content param
```

--------------------------------

### Configure Akismet API Key in Dreamform

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/akismet

This snippet demonstrates how to add the Akismet guard and configure its API key within the `site/config/config.php` file for the tobimori.dreamform plugin. It emphasizes loading the API key securely from an environment variable.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['akismet', /* other guards here */ ],
      'akismet' => [
        'apiKey' => fn () => env('AKISMET_API_KEY')
      ]
    ],
  ],
];
```

--------------------------------

### Define Kirby Plugin for DreamForm Action

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/custom

This snippet shows how to create a basic Kirby plugin in `site/plugins/discord-action/index.php` and define it using `Kirby::plugin()`. This sets up the initial plugin structure required for integrating a custom DreamForm action.

```PHP
// site/plugins/discord-action/index.php

use Kirby\Cms\App as Kirby;

Kirby::plugin('tobimori/discord-action', []);
```

--------------------------------

### Dreamform Plugin Optional Configuration Settings

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/configuration

Defines various optional configuration settings for the tobimori.dreamform plugin, including submission mode, multi-step forms, submission storage, debugging, layouts, and integrations. These settings can be adjusted to customize the plugin's behavior.

```APIDOC
tobimori.dreamform. settings:
  mode:
    Default: 'prg'
    Accepts: 'prg'|'api'|'htmx'
    Description: Set the submission mode for all form submissions
  multiStep:
    Default: true
    Accepts: boolean
    Description: Enable or disable multi-step forms
  storeSubmissions:
    Default: true
    Accepts: boolean
    Description: Whether to store submissions as pages in Kirby
  debug:
    Default: fn () => option('debug')
    Accepts: boolean|callable
    Description: If enabled, sensitive errors are shown on form submission
  layouts:
    Default: ['1/1', '1/2, 1/2']
    Accepts: array
    Description: Enabled layouts for the form builder
  page:
    Default: page://forms
    Accepts: string
    Description: The page where all forms are stored
  integrations.gravatar:
    Default: true
    Accepts: boolean
    Description: If enabled, submissions with email fields fetch an avatar from Gravatar to show in the panel
```

--------------------------------

### Registering DreamForm Calc Guard and Snippet (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

Registers a custom `CalcGuard` class with DreamForm and its associated Kirby snippet. This makes the guard available for use and links its rendering logic. It requires loading the `CalcGuard.php` file.

```php
// [...]

@include_once __DIR__ . '/CalcGuard.php'; // Tell PHP to load our class

DreamForm::register(CalcGuard::class); // Register the class with DreamForm

Kirby::plugin('tobimori/calc-guard', [
  'snippets' => [
    'dreamform/guards/calc' => __DIR__ . '/snippets/calc.php' // Register the Guard snippet with Kirby
  ]
]);
```

--------------------------------

### Complete DreamForm Calculation Guard Class

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

This is the final, complete implementation of the `CalcGuard` class. It integrates the `run()` method for validation, `hasSnippet()` and `type()` for guard identification, and the `generate()` method for creating math questions, demonstrating a fully functional custom guard.

```php
<?php

use Kirby\Cms\App;
use tobimori\DreamForm\Guards\Guard;
use tobimori\DreamForm\Models\SubmissionPage;

class CalcGuard extends Guard
{
  public function run()
  {
    $result = App::instance()->session()->pull('calc-guard-result');
    $value = SubmissionPage::valueFromBody('calc');

    if ($result !== (int) $value) {
      $this->cancel('Sorry, think again! 🤔');
    }
  }

  public static function hasSnippet(): bool
  {
    return true;
  }

  public static function type(): string
  {
    return 'calc';
  }

  public function generate(): string
  {
    [$a, $b] = [rand(0, 9), rand(0, 9)];
    App::instance()->session()->set('calc-guard-result', $a + $b);

    return "What is {$a} + {$b}?";
  }
}
```

--------------------------------

### Dreamform Buttondown API Key Configuration Options

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/buttondown

This section details the configuration options available for the Buttondown integration within the Dreamform plugin, including the API key and simple mode settings.

```APIDOC
Options:
- tobimori.dreamform.fields.buttondown.apiKey:
  - Default: null
  - Accepts: string|callback
  - Description: The API key to communicate with Buttondown
- tobimori.dreamform.fields.buttondown.simpleMode:
  - Default: false
  - Accepts: boolean
  - Description: Simple mode works with the free tier, but does not support updating user data or tags
```

--------------------------------

### Implement Basic DreamForm Discord Action Class

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/custom

This PHP snippet defines the `DiscordAction` class, extending `Action`. It implements the `blueprint()` method to define panel fields for a webhook URL and the `type()` method to set the action's internal identifier. The `run()` method is also defined as a placeholder for the action's core logic.

```PHP
<?php

use tobimori\DreamForm\Actions\Action;

class DiscordAction extends Action
{
  public static function blueprint(): array
  {
    return [
      'title' => 'Discord Message',
      'preview' => 'fields',
      'wysiwyg' => true,
      'icon' => 'discord',
      'fields' => [
        'webhookUrl' => [
          'label' => 'Webhook URL',
          'type' => 'url',
          'placeholder' => 'https://discord.com/api/webhooks/...',
          'width' => '1/3',
          'required' => true
        ]
      ]
    ];
  }

  public function run(): void
  {
    // send the request
  }

  public static function type(): string
  {
    return 'discord';
  }
}
```

--------------------------------

### Dreamform Guards Configuration Options

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/what-are-guards

This section details the available configuration options for Dreamform guards, including their default values, accepted types, and descriptions.

```APIDOC
Property: tobimori.dreamform.guards.available
  Type: array
  Default: ['csrf', 'honeypot']
  Description: Active guards to protect your form
```

--------------------------------

### Enabling DreamForm Guard in Kirby Configuration (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

Enables the registered 'calc' guard by adding it to the `available` array in the `site/config/config.php` file. This activates the guard for use in DreamForm.

```php
// site/config/config.php

return [
  'tobimori.dreamform.guards' => [
    'available' => ['calc', 'csrf', 'honeypot']
  ]
];
```

--------------------------------

### Configure Dreamform to Collect IP and User Agent for Akismet

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/akismet

Since Akismet requires the sender's IP address and user agent for accurate spam detection, this configuration snippet shows how to enable their collection within the tobimori.dreamform plugin's metadata settings in `site/config/config.php`.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [ /* [...] */ ],
    'metadata' => [
        'collect' => [
            'ip',
            'userAgent'
        ]
    ],
  ],
];
```

--------------------------------

### tobimori.dreamform.actions API Options Reference

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/what-are-actions

This section details the configuration options available for managing actions within the 'tobimori.dreamform' plugin. It describes the 'available' property, its default value, accepted types, and purpose for controlling action visibility.

```APIDOC
tobimori.dreamform.actions.available:
  Default: true
  Accepts: boolean|array
  Description: Available actions, true enables all actions
```

--------------------------------

### Dreamform Honeypot Guard Options

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/honeypot

Details the available configuration options for the `tobimori.dreamform.guards.honeypot` guard, specifically `availableFields`, including its default value, accepted types, and purpose.

```APIDOC
tobimori.dreamform.guards.honeypot.availableFields:
  Default: [...]
  Accepts: array
  Description: Available field keys for the honeypot field
```

--------------------------------

### Configure DreamForm Honeypot Guard in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/honeypot

This PHP code snippet demonstrates how to configure the DreamForm Honeypot guard within your `site/config/config.php` file. It shows how to explicitly define which guards are available (e.g., 'honeypot') and how to customize the list of field keys that the Honeypot guard will monitor, such as 'website', 'email', 'name', 'url', and 'birthdate'.

```PHP
// site/config/config.php

return [
  // Settings for the DreamForm plugin
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['honeypot'],
      'honeypot.availableFields' => ['website', 'email', 'name', 'url', 'birthdate'],
    ],
  ],
];
```

--------------------------------

### DreamForm Action Class Methods Reference

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/custom

This section outlines the available methods for a DreamForm action class, including their purpose, parameters, and return types. These methods define the behavior and panel integration of a custom action within the DreamForm framework.

```APIDOC
public static function blueprint(): array
  Returns an array with the blueprint definition used in the panel
public static function type(): string
  Returns the type of the field used internally, also used for accessing the snippet
public static function group(): string
  Customize the group of the action in the panel
public function run(): void
  The logic that's executed when the action is running
public static function isAvailable(FormPage|null $form = null): bool
  Whether the action should be available, used for checking global configuration details, like API keys
```

--------------------------------

### DreamForm Action Class Methods Reference

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/custom

This section documents the various methods available within a DreamForm action, allowing developers to access submission data, form details, block configurations, and control the action's flow by signaling success or cancellation.

```APIDOC
$this->submission(): Access the submission
$this->form(): Access the form
$this->block(): Access the block used to configure the action
$this->success(): End the submission early, and show the success screen
$this->cancel(string $message = null, bool $public = false): Cancel the request with an error message - If $public is false, the error message is only shown when debug mode is enabled
$this->silentCancel(string $message = null): Silently cancel the form submission - Submission will be shown as successful to the user, except if debug mode is enabled
```

--------------------------------

### Dreamform Plugin Field Configuration Options API

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/what-are-fields

This API documentation details the configuration options for Dreamform plugin fields. It specifically describes the `tobimori.dreamform.fields.available` option, which controls the visibility of field types, allowing either all fields or a specific subset.

```APIDOC
tobimori.dreamform.fields.available:
  Description: Available fields, true enables all fields
  Default: true
  Accepts: boolean|array
```

--------------------------------

### Define Basic DreamForm Guard Class Structure

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

This snippet outlines the fundamental structure of a DreamForm guard class. It extends `tobimori\DreamForm\Guards\Guard` and includes the essential `run()` method for execution, and static `hasSnippet()` and `type()` methods for determining snippet rendering and guard identification.

```php
// site/plugins/calc-guard/CalcGuard.php

use tobimori\DreamForm\Guards\Guard;

class CalcGuard extends Guard
{
  public function run()
  {
    // $this->cancel('error message!');
  }

  public static function hasSnippet(): bool
  {
    return true;
  }

  public static function type(): string
  {
    return 'calc';
  }
}
```

--------------------------------

### Configure Dreamform Guards in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/what-are-guards

This snippet demonstrates how to enable or disable available guards for Dreamform by specifying an array of guard types in the `tobimori.dreamform.guards.available` configuration setting within your `site/config/config.php` file. Activating new guards may require additional configuration specific to each guard.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['csrf', 'honeypot', 'turnstile', 'ratelimit', /* other guards here */ ],
    ],
  ],
];
```

--------------------------------

### Configure Buttondown API Key in Dreamform (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/buttondown

This PHP code snippet demonstrates how to add the Buttondown API key to your `config.php` file for the Dreamform plugin. It's recommended to load the key from an environment variable for security.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'actions' => [
      'buttondown.apiKey' => fn () => env('BUTTONDOWN_API_KEY')
    ],
  ],
];
```

--------------------------------

### Initialize DreamForm Custom Field Plugin in Kirby (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/custom

This PHP snippet shows the basic `index.php` file content required to initialize a new Kirby plugin for a custom DreamForm field. It uses `Kirby::plugin` to register the plugin with a unique identifier.

```php
// site/plugins/linkedin-field/index.php

use Kirby\Cms\App as Kirby;

Kirby::plugin('tobimori/linkedin-field', []);
```

--------------------------------

### Configure Available Dreamform Fields in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/what-are-fields

This PHP code snippet demonstrates how to customize the list of available fields for the `tobimori.dreamform` plugin within your `site/config/config.php` file. By specifying an array of field names, you can control which field types are accessible in your forms, or set it to `true` to enable all default fields.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'fields' => [
      'available' => ['text', 'textarea', 'select', 'checkboxes', /* other guards here */ ],
    ],
  ],
];
```

--------------------------------

### Implement Guard Method to Generate Math Question

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

This method generates two random numbers, stores their sum in the session for later validation, and returns a string representing the math question to be displayed to the user. This ensures the question and its answer are linked for the current session.

```php
public function generate(): string
{
  [$a, $b] = [rand(0, 9), rand(0, 9)]; // Generate two random numbers
  App::instance()->session()->set('calc-guard-result', $a + $b); // Store the result in a session

  return "What is {$a} + {$b}?"; // Return the question as string
}
```

--------------------------------

### Configure Available Actions in Kirby CMS config.php

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/what-are-actions

This PHP snippet demonstrates how to explicitly define the available actions for the 'tobimori.dreamform' plugin within your Kirby CMS 'config.php' file. By listing specific action names, you can control which functionalities are accessible, overriding the default behavior where all registered actions are enabled.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'actions' => [
      'available' => ['abort', 'conditional', 'redirect', 'webhook', /* other actions here */ ],
    ],
  ],
];
```

--------------------------------

### Register DreamForm Discord Action Class

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/custom

This snippet demonstrates how to register the `DiscordAction` class with DreamForm in the `index.php` plugin file. It includes the class file and then uses `DreamForm::register()` to make the action available in the Kirby panel, allowing it to be used in forms.

```PHP
// [...]

@include_once __DIR__ . '/DiscordAction.php'; // Tell PHP to load our class

DreamForm::register(DiscordAction::class); // Register the class with DreamForm

Kirby::plugin('tobimori/discord-action', []);
```

--------------------------------

### Implement Guard Run Method for Input Validation

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

This `run()` method retrieves the stored result from the session and the submitted value from the request body. It then compares the submitted value with the expected result. If the value is empty or incorrect, the submission is cancelled with an error message.

```php
public function run()
{
  $result = App::instance()->session()->pull('calc-guard-result'); // Get result from session, and remove it
  $value = SubmissionPage::valueFromBody('calc'); // Get Field value

  // Check if the value doesn't exists or is not equal to the result
  if (empty($value) || $result !== (int) $value) {
    $this->cancel('Sorry, think again! 🤔');
  }
}
```

--------------------------------

### Create Frontend Snippet for Calculation Guard Input

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/custom

This HTML snippet defines the input field for the calculation guard. It includes a label displaying the generated math question and an input field of type 'number' for the user to enter their answer. The snippet ensures the field is properly styled and required for submission.

```html
// site/plugins/calc-guard/snippets/calc.php

<div <?= attr($attr['field']) ?>> <?php /* $attr includes the classes apply to the fields */ ?>
  <label <?= attr(A::merge($attr['label'], ["for" => "calc"])) ?>>
    <span><?= $guard->generate() ?></span><em>*</em> <?php /* Generate the result and show the question */ ?>
  </label>

  <input <?= attr(A::merge($attr['input'], [
    'type' => 'number',
    'id' => 'calc',
    'name' => 'calc',
    'required' => true
  ])) ?>>
</div>
```

--------------------------------

### Configure Dreamform Rate Limit Guard Options

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/ratelimit

Defines the configurable parameters for the rate limit guard, including the maximum number of requests and the time interval over which the limit applies.

```APIDOC
tobimori.dreamform.guards.ratelimit:
  limit:
    description: Limit of requests per interval
    type: int
    default: 10
  interval:
    description: Interval in minutes
    type: int
    default: 3
```

--------------------------------

### Configure DreamForm Field Submission Blueprint and Group (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/custom

This PHP snippet enhances the `LinkedInField` class by defining its submission blueprint and group. The `submissionBlueprint` method specifies how the field's value is displayed in the panel, including its label, icon, and type. The `group` method organizes the field into a custom 'social' category within the block selector, improving user experience.

```PHP
class LinkedInField extends Field
{
  [...]

  public function submissionBlueprint(): array|null
  {
    return [
      'label' => $this->block()->label()->value() ?? 'LinkedIn',
      'icon' => 'linkedin',
      'type' => 'text'
    ];
  }

  public static function group(): string
  {
    return 'social';
  }
}
```

--------------------------------

### Configure IP-based Rate Limit Guard in DreamForm

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/ratelimit

This snippet demonstrates how to add the 'ratelimit' guard to your DreamForm configuration in `site/config/config.php`. It shows how to customize the `limit` (default 10 requests) and `interval` (default 3 minutes) settings for the rate limit. This configuration ensures that form submissions are rate-limited based on IP address.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['ratelimit', /* other guards here */ ],
      'ratelimit' => [
        'limit' => 10,
        'interval' => 3
      ]
    ],
  ],
];
```

--------------------------------

### Creating a Frontend Snippet for DreamForm Custom Field in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/custom

This PHP snippet defines the frontend rendering for the custom 'LinkedInField'. It reuses the existing 'dreamform/fields/text' snippet and sets the input type to 'url' to leverage browser-specific input methods for URL fields, ensuring consistent look and feel.

```php
<?php

/**
 * @var \tobimori\DreamForm\Models\Submission|null $submission
 *
 * @var \Kirby\Cms\Block $block
 * @var \tobimori\DreamForm\Fields\NumberField $field
 * @var \tobimori\DreamForm\Models\FormPage $form
 * @var array $attr
 */

snippet('dreamform/fields/text', [
  'block' => $block,
  'field' => $field,
  'form' => $form,
  'attr' => $attr,
  'type' => 'url'
]);
```

--------------------------------

### Registering and Enabling a Custom DreamForm Field in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/custom

This PHP code demonstrates how to register the custom 'LinkedInField' class and its associated frontend snippet with DreamForm and Kirby, respectively. This step is crucial for making the custom field available for use within the Kirby panel and for rendering it correctly on the frontend.

```php
// [...]

@include_once __DIR__ . '/LinkedInField.php'; // Tell PHP to load our class

DreamForm::register(LinkedInField::class); // Register the class with DreamForm

Kirby::plugin('tobimori/linkedin-field', [
  'snippets' => [
    'dreamform/fields/linkedin' => __DIR__ . '/snippets/linkedin.php' // Register the field snippet with Kirby
  ]
]);
```

--------------------------------

### DreamForm Field Class API Reference

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/custom

Reference for methods available in DreamForm custom field classes, including required methods for basic functionality and optional methods for advanced customization like validation, submission handling, and availability checks.

```APIDOC
Field Class Methods:
- public static function blueprint(): array
    Description: Returns an array with the blueprint definition used in the panel.
- public static function type(): string
    Description: Returns the type of the field used internally, also used for accessing the snippet.
- public function validate(): true|string
    Description: Validates the field value ($this->value()). Returns the error message as string or true if validation was successful.
- protected function sanitize(\Kirby\Content\Field $field): \Kirby\Content\Field
    Description: Returns the sanitized field value.
- public function afterSubmit(SubmissionPage $submission): void
    Description: Runs logic after the submission, such as uploading files.
    Parameters:
        submission (SubmissionPage): The submission object.
- public function submissionBlueprint(): array|null
    Description: Returns an array with the blueprint definition used when viewing a submission.
- public static function isAvailable(FormPage|null $form = null): bool
    Description: Checks whether the field should be available, used for checking global configuration details, like API keys.
    Parameters:
        form (FormPage|null): The form page object (optional).
- public static function group(): string
    Description: Customizes the group of the field in the panel.
- public static function hasValue(): bool
    Description: Indicates whether the field stores a value or is entirely cosmetic (like a heading).
```

--------------------------------

### DreamForm Required Configuration Option: Encryption Secret

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/configuration

Documents the `tobimori.dreamform.secret` configuration option, which is a crucial setting for DreamForm. This secret is used to encrypt and decrypt published values, ensuring data security. It can be set as a string or a callable function.

```APIDOC
tobimori.dreamform.secret:
  Default: null
  Accepts: string|callable
  Description: The encryption secret used to encrypt & decrypt published values
```

--------------------------------

### Kirby CMS Form Block Blueprint Definition (YAML)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/using-forms

This YAML configuration defines a 'Form Block' blueprint for Kirby CMS. It specifies the block's title, icon, preview behavior, and includes a 'form' field that extends the 'dreamform' plugin's form field, allowing content editors to select a pre-defined form.

```yaml
title: Form Block
icon: survey
preview: fields
wysiwyg: true

fields:
  form:
    label: Select your form
    extends: dreamform/fields/form
```

--------------------------------

### Implement File Firewall for DreamForm Uploads in Kirby CMS (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/file-upload

This PHP code snippet demonstrates how to implement a file firewall for 'dreamform-upload' files within Kirby CMS. It defines a custom plugin that includes a route to handle protected file downloads, ensuring only authenticated users can access them. Additionally, it overrides the 'file::url' and 'file::version' components to redirect protected file URLs and prevent direct media access, enhancing security for sensitive data.

```php
<?php

use Kirby\Toolkit\Str;
use Kirby\Uuid\Uuid;
use Kirby\Cms\App;

App::plugin('dreamform/files-firewall', [
  'routes' => [
    [
      'pattern' => '_form/(:any)',
      'action'  => function ($filename) {
        if (
          kirby()->user() &&
          $file = Uuid::for("file://{$filename}")?->model()
        ) {
          /** @var \Kirby\Cms\File $file */
          return $file->download();
        }

        return site()->errorPage();
      },
    ],
  ],
  'components' => [
    'file::url' => function ($kirby, $file) {
      if ($file->template() === 'dreamform-upload') {
        return $kirby->url() . '/_form/' . Str::replace($file->uuid()->toString(), 'file://', '');
      }

      return $file->mediaUrl();
    },
    'file::version' => function ($kirby, $file, array $options = []) {
      static $original;

      // if the file is protected, return the original file
      if ($file->template() === 'dreamform-upload') {
        return $file;
      }

      // if static $original is null, get the original component
      if ($original === null) {
        $original = $kirby->nativeComponent('file::version');
      }

      // and return it with the given options
      return $original($kirby, $file, $options);
    }
  ],
]);
```

--------------------------------

### Defining a Custom DreamForm Field Class in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/fields/custom

This PHP code defines a custom field class, 'LinkedInField', by extending the base DreamForm Field class. It implements the 'blueprint()' method to define the field's appearance and configuration in the Kirby panel, and the 'type()' method to specify its internal identifier.

```php
<?php

use tobimori\DreamForm\Fields\Field;

class LinkedInField extends Field
{
  public static function blueprint(): array
  {
    return [
      'title' => 'LinkedIn',
      'label' => '{{ label }}',
      'preview' => 'text-field',
      'wysiwyg' => true,
      'icon' => 'linkedin',
      'tabs' => [
        'field' => [
          'label' => t('dreamform.field'),
          'fields' => [
            'key' => 'dreamform/fields/key',
            'label' => 'dreamform/fields/label',
            'placeholder' => 'dreamform/fields/placeholder',
          ]
        ],
        'validation' => [
          'label' => t('dreamform.validation'),
          'fields' => [
            'required' => 'dreamform/fields/required',
            'errorMessage' => 'dreamform/fields/error-message',
          ]
        ]
      ]
    ];
  }

  public static function type(): string
  {
    return 'linkedin';
  }
}
```

--------------------------------

### Send Discord Webhook Request with PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/actions/custom

This PHP code demonstrates how to send a POST request to a Discord webhook endpoint using Kirby's Remote class. It constructs a JSON payload from submission values and handles potential errors by canceling the action if the request fails.

```php
<?php

class DiscordAction extends Action
{
  [...]

  public function run(): void
  {
    try {
      $request = Remote::post($this->block()->webhookUrl()->value(), [
        'headers' => [
          'Content-Type' => 'application/json'
        ],
        'data' => Json::encode([
          'content' => A::join(A::map($this->submission()->values()->toArray(), function ($value, $key) {
            return "**{$key}**: {$value}";
          }), "\n"),
          'embeds' => null,
          'attachments' => []
        ])
      ]);

      if ($request->code() > 299) {
        $this->cancel();
      }
    } catch (Throwable $e) {
      $this->cancel($e->getMessage());
    }
  }
}
```

--------------------------------

### Kirby CMS Form Block Rendering Snippet (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/setup/using-forms

This PHP snippet is used to render the 'Form Block' on the frontend of a Kirby CMS site. It calls the 'dreamform' plugin's form snippet, passing the selected form page object (retrieved from the block's 'form' field) as an argument. This ensures the correct form is displayed based on the content editor's selection.

```php
<?php snippet('dreamform/form', ['form' => $block->form()->toPage()]); ?>
```

--------------------------------

### Configure DreamForm Permissions in Kirby User Blueprint

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/permissions

This YAML snippet demonstrates how to define DreamForm-specific permissions within a Kirby user blueprint file (e.g., `editor.yml`). It grants full access to forms (create, update, delete, duplicate, change title, status, slug) and submissions (access, delete) for a user role.

```YAML
# /site/blueprints/users/editor.yml

title: Editor
permissions:
  tobimori.dreamform:
    accessForms: true
    createForms: true
    updateForms: true
    deleteForms: true
    duplicateForms: true
    changeFormTitle: true
    changeFormStatus: true
    changeFormSlug: true
    accessSubmissions: true
    deleteSubmissions: true
```

--------------------------------

### Override Dreamform Success Snippet in PHP

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/success-page

This PHP snippet demonstrates the structure of the `site/snippets/dreamform/success.php` file, which is automatically rendered upon successful form submission. It shows how to access the `$form` variable to retrieve field values and how to use the `$attr` array for HTML attributes. The snippet also includes PHPDoc type hints for available variables.

```PHP
<?php

/**
 * @var \Kirby\Cms\Page $page
 * @var \tobimori\Dreamform\Models\FormPage $form
 * @var array|null $attr
 */ ?>

<div <?= attr($attr['success']) ?>>
  <?= $form->successMessage() ?>
</div>
```

--------------------------------

### Configure Cloudflare Turnstile Guard in DreamForm (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/turnstile

This snippet demonstrates how to add Cloudflare Turnstile as a guard in your DreamForm configuration. It requires adding 'turnstile' to the list of available guards and providing the `siteKey` and `secretKey`, which should ideally be loaded from environment variables for enhanced security.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['turnstile', /* other guards here */ ],
      'turnstile' => [
        'siteKey' => fn () => env('TURNSTILE_SITE_KEY'),
        'secretKey' =>  fn () => env('TURNSTILE_SECRET_KEY')
      ]
    ]
  ]
];
```

--------------------------------

### Execute Code Before DreamForm Submission Processing (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/hooks

This hook, `dreamform.submit:before`, is triggered just before a DreamForm submission begins its processing. It provides an opportunity to inject custom logic or validations that need to occur prior to the main submission handling. The hook function receives the submission page and form page objects as arguments.

```PHP
return [
  'hooks' => [
    'dreamform.upload:before' => function (\tobimori\DreamForm\Models\SubmissionPage $submission, \tobimori\DreamForm\Models\FormPage $form) {
      // your code goes here
    }
  ]
];
```

--------------------------------

### DreamForm Turnstile Guard Configuration Options

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/guards/turnstile

Defines the configurable options for the DreamForm Turnstile guard. These settings control how the Cloudflare Turnstile captcha is integrated and behaves within your site, including necessary keys, script loading, and visual theme.

```APIDOC
tobimori.dreamform.guards.turnstile:
  siteKey:
    Default: null
    Accepts: string|callback
    Description: The Turnstile sitekey is used to invoke Turnstile on your site.
  secretKey:
    Default: null
    Accepts: string|callable
    Description: The Turnstile secret key allows communication between DreamForm and Cloudflare to validate the response.
  injectScript:
    Default: true
    Accepts: boolean
    Description: Whether the client-side Turnstile script should be injected implicitly by the plugin.
  theme:
    Default: 'auto'
    Accepts: 'auto'|'light'|'dark'
    Description: Theme to render the captcha with, automatically adapting to user preferences or set explicitly.
```

--------------------------------

### Render Dreamform Form Snippet with Custom Attributes (PHP)

Source: https://plugins.andkindness.com/dreamform/docs/dreamform/docs/developers/styling

This PHP snippet demonstrates how to render a Dreamform form using `snippet('dreamform/form')` and pass an array of attributes via the `attr` option. These attributes allow for attaching classes to various form elements (e.g., form, row, column, field, input) and can be specified generally or overridden for specific field types like textarea, text, or select.

```php
<?php snippet('dreamform/form', [
	'form' => $page->myForm()->toPage(),
	'attr' => [
		// General attributes
		'form' => ['class' => 'form'],
		'row' => [],
		'column' => [],
		'field' => [],
		'label' => [],
		'error' => [],
		'input' => [],
		'button' => [],

		// Field-specific attributes
		'textarea' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
		],
		'text' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
		],
		'select' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
		],
		'number' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
		],
		'file' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
		],
		'email' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
		],
		'radio' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
			'row' => []
		],
		'checkbox' => [
			'field' => [],
			'label' => [],
			'error' => [],
			'input' => [],
			'row' => []
		],

		'success' => [], // Success message
		'inactive' => [], // Inactive message
	]
]); ?>
```
Tokens:
Raw