Formie

https://verbb.io/craft-plugins/formie/docs
Admin
Formie is a powerful and flexible form builder plugin for Craft CMS, enabling users to create,...
Tokens:153,805
Snippets:1,778
Trust Score:8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Local Redirect URI

Source: https://verbb.io/craft-plugins/formie/docs/integrations/miscellaneous

This is an example of a typical redirect URI for a local development environment.

```text
http://formie.test/actions/formie/integrations/callback
```

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

### Example PDF Template

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/pdf-templates

This is an example of a basic HTML template for generating a PDF. It includes variables for site name and content.

```html
<h1>Thanks for your email enquiry. The below email was sent from {{ siteName }}.</h1>

{{ contentHtml }}
```

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

### Formie Page Start Hook Example

Source: https://verbb.io/craft-plugins/formie/docs/developers/hooks

Utilize the `formie.page.start` hook to insert content or variables before the page legend. This hook runs at the beginning of the page rendering.

```php
Craft::$app->getView()->hook('formie.page.start', function(array &$context) {
    // Add a variable to be accessible in the context object.
    $context['foo'] = 'bar';

    // Optionally return a string
    return '<p>Hey!</p>';
});
```

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

### Install Formie via Composer

Source: https://verbb.io/craft-plugins/formie/docs/get-started/installation-setup

Use Composer to add the Formie package to your project and then install it via the Craft console.

```bash
composer require verbb/formie && php craft plugin/install formie
```

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

### Formie Form Start Hook Example

Source: https://verbb.io/craft-plugins/formie/docs/developers/hooks

Use the `formie.form.start` hook to add content or variables before the form title. This hook is executed at the beginning of the form element.

```php
Craft::$app->getView()->hook('formie.form.start', function(array &$context) {
    // Add a variable to be accessible in the context object.
    $context['foo'] = 'bar';

    // Optionally return a string
    return '<p>Hey!</p>';
});
```

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

### Fetching a Single Form by Handle

Source: https://verbb.io/craft-plugins/formie/docs/getting-elements/form-queries

This example demonstrates how to fetch a single form by its handle using the `.one()` method after setting the `handle` parameter.

```APIDOC
## Example

We can display a form for a given handle by doing the following:
  1. Create a form query with `craft.formie.forms()`.
  2. Set the handle parameter on it.
  3. Fetch a single form with `.one()` and output.

### Twig
```twig
{# Create a form query with the 'handle' parameter #}
{% set formQuery = craft.formie.forms()
    .handle('contactForm') %}

{# Fetch the Form #}
{% set form = formQuery.one() %}

{# Display their contents #}
<p>{{ form.title }}</p>
```
```

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

### GraphQL JSON Response Example

Source: https://verbb.io/craft-plugins/formie/docs/developers/graphql

This is an example of a JSON response when querying for form data. It shows the structure of the returned data, including field-specific properties.

```json
{
    "data": {
        "formieForm": {
            "title": "Contact Form",
            "handle": "contactForm",
            "settings": {
                "errorMessageHtml": "Couldn’t save submission due to errors."
            },
            "pages": [
                {
                    "label": "Page 1",
                    "rows": [
                        {
                            "rowFields": [
                                {
                                    "label": "Your Name",
                                    "handle": "yourName",
                                    "type": "verbb\\formie\\fields\\Name",
                                    "displayName": "Name",
                                    "fields": [
                                        {
                                            "label": "Prefix",
                                            "enabled": false,
                                            "required": false
                                        },
                                        {
                                            "label": "First Name",
                                            "enabled": true,
                                            "required": true
                                        },
                                        {
                                            "label": "Middle Name",
                                            "enabled": false,
                                            "required": false
                                        },
                                        {
                                            "label": "Last Name",
                                            "enabled": true,
                                            "required": true
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "rowFields": [
                                {
                                    "label": "Email Address",
                                    "handle": "emailAddress",
                                    "type": "verbb\\formie\\fields\\Email",
                                    "displayName": "Email",
                                    "placeholder": "eg. psherman@wallaby.com"
                                }
                            ]
                        },
                        {
                            "rowFields": [
                                {
                                    "label": "Message",
                                    "handle": "message",
                                    "type": "verbb\\formie\\fields\\MultiLineText",
                                    "displayName": "MultiLineText"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}
```

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

### Example URL for Pre-Populating Form Fields

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/populating-forms

This URL demonstrates how query parameters can be used to pre-populate various form fields like text, email, and multi-line text.

```html
http://mysite.com/contact-us?first_name=Peter&last_name=Sherman&email=psherman@wallaby.com.au&content=I want to know more!&utm=xxxxxxxxxxx
```

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

### Form Submission Response Example

Source: https://verbb.io/craft-plugins/formie/docs/developers/graphql

An example JSON response for a form submission query, showing the structure of retrieved data including title, name, email, and message.

```json
{
    "data": {
        "formieSubmissions": [
            {
                "title": "2020-07-24 22:01:59",
                "yourName": "Peter Sherman",
                "emailAddress": "psherman@wallaby.com",
                "message": "Just wanted to say hi!"
            }
        ]
    }
}
```

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

### Example Email Marketing Integration - Formie

Source: https://verbb.io/craft-plugins/formie/docs/developers/custom-integration

Implement this class to create a custom email marketing integration. It defines display information, settings, and the payload submission logic.

```php
<?php
namespace modules\sitemodule;

use verbb\formie\base\EmailMarketing;
use verbb\formie\elements\Form;
use verbb\formie\elements\Submission;
use verbb\formie\models\IntegrationCollection;
use verbb\formie\models\IntegrationField;
use verbb\formie\models\IntegrationFormSettings;

use Craft;

class ExampleEmailMarketing extends EmailMarketing
{
    public static function displayName(): string
    {
        return Craft::t('formie', 'Example Email Marketing');
    }

    public function getIconUrl(): string
    {
        return Craft::$app->getAssetManager()->getPublishedUrl("@modules/mymodule/resources/icon.svg", true);
    }

    public function getDescription(): string
    {
        return Craft::t('formie', 'This is an example email marketing integration.');
    }

    public function getSettingsHtml(): string
    {
        $variables = $this->getSettingsHtmlVariables();

        return Craft::$app->getView()->renderTemplate('path/to/settings', $variables);
    }

    public function getFormSettingsHtml($form): string
    {
        $variables = $this->getFormSettingsHtmlVariables($form);

        return Craft::$app->getView()->renderTemplate('path/to/form-settings', $variables);
    }

    public function fetchFormSettings()
    {
        $settings = [];

        // Fetch your lists from your provider's API
        $lists = $this->request('GET', 'lists');

        foreach ($lists as $list) {
            // Fetch your lists' fields from your provider's API
            $fields = $this->request('GET', 'fields');

            // Add some standard fields not included from the API
            $listFields = [
                new IntegrationField([
                    'handle' => 'email',
                    'name' => Craft::t('formie', 'Email'),
                    'required' => true,
                ]),
            ];

            // Add the custom fields to our collection
            foreach ($fields as $key => $field) {
                $listFields[] = new IntegrationField([
                    'handle' => $field['id'],
                    'name' => $field['name'],
                    'type' => $field['type'],
                ]);
            }

            // Add a new collection to our settings, including fields specific for it
            $settings['lists'][] = new IntegrationCollection([
                'id' => $list['id'],
                'name' => $list['name'],
                'fields' => $listFields,
            ]);
        }

        return new IntegrationFormSettings($settings);
    }

    public function sendPayload(Submission $submission): bool
    {
        // Fetch the form settings for our field mapping
        $fieldValues = $this->getFieldMappingValues($submission, $this->fieldMapping);

        // Construct a payload to send
        $payload = [
            'listId' => $this->listId,
            'contact' => $fieldValues,
        ];

        // Send the payload to our API endpoint via POST request. This also handles the before/after sending payload
        // events, which we can check on next
        $response = $this->deliverPayload($submission, 'subscribe', $payload);

        // The response might have failed, or an event returned this as invalid
        if ($response === false) {
            return false;
        }

        return true;
    }
}

```

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

### Advanced Theme Configuration Example

Source: https://verbb.io/craft-plugins/formie/docs/theming/theme-config

Demonstrates multiple theme configuration options simultaneously, including removing wrappers, resetting classes, changing element tags, and adding custom classes with Tailwind CSS.

```twig
{{ craft.formie.renderForm('contactForm', {
    themeConfig: {
        formWrapper: false,

        form: {
            resetClass: true,
            attributes: {
                id: 'my-form',
            },
        },

        formContainer: {
            tag: 'fieldset',
        },

        field: {
            attributes: {
                class: 'p-4 w-full mb-4',
            },
        },

        fieldInput: {
            attributes: {
                class: 'border border-red-500',
            },
        },
    },
}) }}
```

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

### Example Email Notification Output

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/email-templates

This is an example of the rendered HTML email body, including static text and dynamically inserted form field values.

```html
Subject: Thanks for your email

Body:

Thanks for your email enquiry. The below email was sent from Craft Test Site.

**First Name:**
Peter

**Last Name:**
Sherman

**Email Address**
psherman@wallaby.com

**Message**
Just wanted to say, I love the new website!

```

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

### Render Login Form with Error Handling

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/craft-forms

A complete example of a login form including error display and redirect handling, using Formie for field management.

```twig
{% set form = craft.formie.forms.handle('login').one() %}

{% do craft.formie.registerAssets(form) %}

<form method="post" accept-charset="UTF-8" data-fui-form="{{ form.configJson }}">
    {{ actionInput('users/login') }}
    {{ csrfInput() }}

    {% if errorMessage is defined %}
        <p>{{ errorMessage }}</p>
    {% endif %}

    {% if form.getRedirectUrl() %}
        {{ redirectInput(form.getRedirectUrl()) }}
    {% endif %}

    {{ craft.formie.renderPage(form, null, {
        fieldNamespace: '',
    }) }}
</form>
```

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

### Example Email Content with Variables

Source: https://verbb.io/craft-plugins/formie/docs/feature-tour/email-notifications

Demonstrates how dynamic content from Craft or form submissions can be pulled into email notifications. Use the 'All Fields' option to include submission data.

```text
**First Name:**
Peter

**Last Name:**
Sherman

**Email**
psherman@wallaby.com

**Message**
Just wanted to say, I love the new website!
```

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

### Form Field Queries

Source: https://verbb.io/craft-plugins/formie/docs/developers/graphql

Examples of how to query different types of form fields, including those with nested data structures like Address, Group, and Repeater.

```APIDOC
## Querying Form Fields

### Description
This section demonstrates how to query form fields, including specific field types that contain nested data.

### GraphQL Query Example (Sub-Fields)
```graphql
{
    formieForm (handle: "contactForm") {
        title
        handle

        formFields {
            label

            ... on Field_Name {
                nestedRows {
                    fields {
                        label
                    }
                }
            }

            ... on Field_Address {
                fields {
                    label
                }
            }
        }
    }
}
```

### GraphQL Query Example (Nested Fields)
```graphql
{
    formieForm (handle: "contactForm") {
        title
        handle

        formFields {
            label

            ... on Field_Group {
                nestedRows {
                    fields {
                        label
                    }
                }
            }
        }
    }
}
```
```

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

### Complete Form Template Example

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/custom-rendering

This comprehensive template renders a Formie form, including asset registration, submission handling, error display, and field rendering. It requires fetching the form by handle and setting up necessary attributes and hidden inputs.

```twig
{# Fetch the form we require #}
{% set form = craft.formie.forms.handle('contactUs').one() %}

{# Ensure the CSS/JS is rendered, according to the Form Template location #}
{% do craft.formie.registerAssets(form.handle) %}

{# Fetch the current submission - if there is one #}
{% set submission = form.getCurrentSubmission() %}
{% set submitted = craft.formie.plugin.service.getFlash(form.id, 'submitted') %}

{# Show any error or success messages for the submission #}
{% set flashNotice = craft.formie.plugin.service.getFlash(form.id, 'notice') %}
{% set flashError = craft.formie.plugin.service.getFlash(form.id, 'error') %}

{% if flashNotice %}
    <div role="alert">
        {{ flashNotice | raw }}
    </div>
{% endif %}

{% if flashError %}
    <div role="alert">
        {{ flashError | raw }}
    </div>
{% endif %}

{# Generate required attributes for the `<form>` element #}
{% set attributes = {
    id: form.formId,
    method: 'post',
    data: {
        config: form.configJson,
    },
} %}

<form {{ attr(attributes) }}>
    {{ actionInput('formie/submissions/submit') }}
    {{ hiddenInput('handle', form.handle) }}
    {{ csrfInput() }}

    {# Ensure we update the same submission on subsequent saves (if validation fails) #}
    {% if submission and submission.id %}
        {{ hiddenInput('submissionId', submission.id) }}
    {% endif %}

    {# Show any validation errors for the form #}
    {% set errors = submission.getErrors('form') ?? null %}
    {% if errors %}
        {% for error in errors %}
            {{ error }}
        {% endfor %}
    {% endif %}

    {# Render each field, according to its field template #}
    {% for field in form.getFields() %}
        {% namespace field.namespace %}
            {% set id = (form.handle | kebab) ~ '-' ~ (field.handle | kebab) %}
            {% set labelId = "#{id}-label" %}

            {# Set required attributes for the field #}
            {% set inputOptions = {
                id: id,
                labelId: labelId,
            } %}

            {# Fetch the value if one exists, or use the default #}
            {% set value = attribute(submission, field.handle) ?? field.defaultValue ?? null %}
            {% set errors = submission.getErrors(field.handle) ?? null %}

            {{ field.getFrontEndInputHtml(form, value, inputOptions) }}

            {# Show any field-specific errors #}
            {% if errors %}
                {% for error in errors %}
                    {{ error }}
                {% endfor %}
            {% endif %}
        {% endnamespace %}
    {% endfor %}

    {% hook 'formie.buttons.before' %}

    <button type="submit">Submit</button>
</form>
```

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

### Populate Element Fields

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/populating-forms

For element fields (Entries, Categories, Tags, Users, etc.), provide an array of element IDs to pre-select them. This example shows populating an Entries field.

```twig
{% do craft.formie.populateFormValues(form, {
    entriesField: [123, 5625],
}) %}
```

```twig
{% do craft.formie.populateFormValues(form, {
    productsField: [6457],
}) %}
```

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

### Custom URL Parameter for Multiple Element IDs

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/populating-forms

This example shows how to handle multiple element IDs using a custom URL parameter format, such as comma-separated values.

```html
entries=2242,1101
```

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

### Configure Table Buttons in Rich Text Field

Source: https://verbb.io/craft-plugins/formie/docs/get-started/configuration

This example configures the 'table' button to include specific table manipulation tools like inserting and deleting tables, and adding/deleting columns and rows.

```json
{
    "buttons": ["table", "bold", "italic"],
    "table": ["insert-table", "delete-table", "add-col-before", "delete-col", "add-row-before", "delete-col"]
}
```

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

### Custom Integration Element Example

Source: https://verbb.io/craft-plugins/formie/docs/developers/custom-integration

Extends the base `Element` class to define a custom integration. Implement methods like `displayName`, `getIconUrl`, `getDescription`, `getSettingsHtml`, `getFormSettingsHtml`, `fetchFormSettings`, and `sendPayload` to customize its behavior.

```php
<?php
namespace modules\sitemodule;

use verbb\formie\base\Element;
use verbb\formie\elements\Form;
use verbb\formie\elements\Submission;
use verbb\formie\models\IntegrationField;
use verbb\formie\models\IntegrationFormSettings;

use Craft;

class ExampleElement extends Element
{
    public static function displayName(): string
    {
        return Craft::t('formie', 'Example Element');
    }

    public function getIconUrl(): string
    {
        return Craft::$app->getAssetManager()->getPublishedUrl("@modules/mymodule/resources/icon.svg", true);
    }

    public function getDescription(): string
    {
        return Craft::t('formie', 'This is an example element.');
    }

    public function getSettingsHtml(): string
    {
        $variables = $this->getSettingsHtmlVariables();

        return Craft::$app->getView()->renderTemplate('path/to/settings', $variables);
    }

    public function getFormSettingsHtml($form): string
    {
        $variables = $this->getFormSettingsHtmlVariables($form);

        return Craft::$app->getView()->renderTemplate('path/to/form-settings', $variables);
    }

    public function fetchFormSettings()
    {
        $customFields = [];

        // Create `IntegrationField` instances for every field
        foreach ($elementGroup->getFields() as $field) {
            $fields[] = new IntegrationField([
                'handle' => $field->id,
                'name' => $field->name,
                'type' => get_class($field),
                'required' => $field->required,
            ]);
        }

        return new IntegrationFormSettings([
            'elements' => $customFields,
            'attributes' => $this->getElementAttributes(),
        ]);
    }

    public function getElementAttributes()
    {
        return [
            new IntegrationField([
                'name' => Craft::t('app', 'Title'),
                'handle' => 'title',
            ]),
            new IntegrationField([
                'name' => Craft::t('app', 'Slug'),
                'handle' => 'slug',
            ]),
        ];
    }

    public function sendPayload(Submission $submission): bool
    {
        $element = new YourElement();

        // Fetch the attribute values from mapping
        $attributeValues = $this->getFieldMappingValues($submission, $this->attributeMapping, $this->getElementAttributes());

        // Populate the attributes from attribute-mapping
        foreach ($attributeValues as $elementFieldHandle => $fieldValue) {
            $element->{$elementFieldHandle} = $fieldValue;
        }

        // Fetch the form settings for `elements` - we need this to parse values correctly
        $fields = $this->getFormSettingValue('elements')->fields ?? [];

        // Fetch the field values from mapping
        $fieldValues = $this->getFieldMappingValues($submission, $this->fieldMapping, $fields);

        // Populate the custom field values
        $element->setFieldValues($fieldValues);

        // Save the element
        if (!Craft::$app->getElements()->saveElement($element)) {
            return false;
        }

        return true;
    }
}

```

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

### Example CRM Integration Class

Source: https://verbb.io/craft-plugins/formie/docs/developers/custom-integration

Extend the `Crm` class to create a custom integration. Implement methods like `displayName`, `getIconUrl`, `getDescription`, `getSettingsHtml`, `getFormSettingsHtml`, `fetchFormSettings`, and `sendPayload` to define your integration's behavior and data handling.

```php
<?php
namespace modules\sitemodule;

use verbb\formie\base\Crm;
use verbb\formie\elements\Form;
use verbb\formie\elements\Submission;
use verbb\formie\models\IntegrationField;
use verbb\formie\models\IntegrationFormSettings;

use Craft;

class ExampleCrm extends Crm
{
    public $contactFieldMapping;
    public $dealFieldMapping;
    public $leadFieldMapping;

    public static function displayName(): string
    {
        return Craft::t('formie', 'Example CRM');
    }

    public function getIconUrl(): string
    {
        return Craft::$app->getAssetManager()->getPublishedUrl("@modules/mymodule/resources/icon.svg", true);
    }

    public function getDescription(): string
    {
        return Craft::t('formie', 'This is an example email marketing integration.');
    }

    public function getSettingsHtml(): string
    {
        $variables = $this->getSettingsHtmlVariables();

        return Craft::$app->getView()->renderTemplate('path/to/settings', $variables);
    }

    public function getFormSettingsHtml($form): string
    {
        $variables = $this->getFormSettingsHtmlVariables($form);

        return Craft::$app->getView()->renderTemplate('path/to/form-settings', $variables);
    }

    public function fetchFormSettings()
    {
        // Build a collection of fields for each data object we want to map
        $contactFields = [
            new IntegrationField([
                'handle' => 'email',
                'name' => Craft::t('formie', 'Email'),
                'required' => true,
            ]),
            new IntegrationField([
                'handle' => 'name',
                'name' => Craft::t('formie', 'Name'),
            ]),
        ];

        $dealFields = [
            new IntegrationField([
                'handle' => 'title',
                'name' => Craft::t('formie', 'Title'),
                'required' => true,
            ]),
        ];

        $leadFields = [
            new IntegrationField([
                'handle' => 'title',
                'name' => Craft::t('formie', 'Title'),
                'required' => true,
            ]),
        ];

        return new IntegrationFormSettings([
            'contact' => $contactFields,
            'deal' => $dealFields,
            'lead' => $leadFields,
        ]);
    }

    public function sendPayload(Submission $submission): bool
    {
        // Fetch the form settings for our field mapping - for each collection of data
        $contactValues = $this->getFieldMappingValues($submission, $this->contactFieldMapping, 'contact');
        $dealValues = $this->getFieldMappingValues($submission, $this->dealFieldMapping, 'deal');
        $leadValues = $this->getFieldMappingValues($submission, $this->leadFieldMapping, 'lead');

        // Construct and send our Contact data
        $response = $this->deliverPayload($submission, 'contacts', [
            'contact' => $contactValues,
        ]);

        if ($response === false) {
            return false;
        }

        // Construct and send our Deal data
        $response = $this->deliverPayload($submission, 'deals', [
            'deal' => $dealValues,
        ]);

        if ($response === false) {
            return false;
        }

        // Construct and send our Lead data
        $response = $this->deliverPayload($submission, 'leads', [
            'lead' => $leadValues,
        ]);

        if ($response === false) {
            return false;
        }

        return true;
    }
}

```

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

### Initialize Formie Form with Vue.js

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Import Formie's JavaScript library and use the `Formie` factory to initialize and destroy forms within a Vue.js application. Ensure the import path is correct for your project setup.

```javascript
import Vue from 'vue';
import { Formie } from '../../../vendor/verbb/formie/src/web/assets/frontend/src/js/formie-lib';

new Vue({
    el: '#app',

    data() {
        return {
            FormieInstance: null,
        }
    },

    mounted() {
        var $form = document.getElementById("formie-form-1");

        // Create an instance of our Formie JS library - the "factory"
        this.FormieInstance = new Formie();

        // Initialise a form from its DOM element
        this.FormieInstance.initForm($form);
    },

    methods: {
        destroyForm() {
            var $form = document.getElementById("formie-form-1010");

            this.FormieInstance.destroyForm($form)
        }
    },
});
```

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

### Query Forms

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/available-variables

Use `craft.formie.forms()` to retrieve form objects. Pass a query to filter results, for example, by form handle. Use `.one()` to get a single form.

```twig
{% set form = craft.formie.forms({ handle: 'contactForm' }).one() %}
```

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

### Example Proxy Redirect URI

Source: https://verbb.io/craft-plugins/formie/docs/integrations/miscellaneous

This is an example of how the redirect URI is modified when using the Formie Proxy Redirect URI.

```text
https://proxy.verbb.io?return=http://formie.test/actions/formie/integrations/callback
```

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

### Listen for Rich Text Editor Initialization

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

The `afterInit` event is triggered after the Pell editor is fully initialized. Access the rich text instance via `e.detail.richText`.

```javascript
// Fetch all Multi-Line Text fields - specifically the textarea. Events are bound on the textarea element
let $fields = document.querySelectorAll('[data-field-type="multi-line-text"] textarea');

// For each field, bind on the `afterInit` event
$fields.forEach($field => {
    $field.addEventListener('afterInit', (e) => {
        let richText = e.detail.richText;
    });
});
```

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

### Form Factory Usage

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Demonstrates how to access the Form Factory and retrieve form instances using different methods after the 'onFormieInit' event.

```APIDOC
## Form Factory

The `formie.js` provides a Form Factory to manage collections of forms. You can access this factory and retrieve form instances in several ways:

```javascript
document.addEventListener('onFormieInit', (e) => {
    // Fetch the Form Factory once it's been loaded
    let Formie = e.detail.formie;

    // Get an already-initialised form by DOM node
    let $form = document.getElementById("formie-form-1");
    let form = Formie.getForm($form);

    // Get an already-initialised form by its ID
    let form = Formie.getFormById('1');

    // Get an already-initialised form by its handle
    let form = Formie.getFormByHandle('myForm');
});
```

**Note:** The `onFormieInit` event is used because `formie.js` is loaded with `defer` and forms are only initialized when visible.
```

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

### Listen for Form Initialization with Vanilla JS

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

The `onFormieInit` event fires when Formie initializes a form that becomes visible on the screen. Access form details like the Formie instance, form element, and form ID from the event details.

```javascript
document.addEventListener('onFormieInit', (e) => {
    // The instance of the Formie JS library
    let Formie = e.detail.formie;

    // The `<form>` HTML element
    let $form = e.detail.$form;

    // The instance of the Formie form class, which encapsulates most logic
    let form = e.detail.form;

    // The `formId` of the form, used as a unique identifier
    let formId = e.detail.formId;

    // ...
});
```

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

### Example Custom Email Template

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/email-templates

This is an example of a custom HTML email template. It uses Twig variables like {{ siteName }} and {{ contentHtml }} to dynamically insert content. Place this file in your Craft templates directory, e.g., `templates/_emails/index.html`.

```html
<!doctype html>
<html>
    <head>
        <title>Thanks for your email</title>
    </head>

    <body>
        <h1>Thanks for your email enquiry. The below email was sent from {{ siteName }}.</h1>

        {{ contentHtml }}
    </body>
</html>
```

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

### Get Instructions Position

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/available-variables

Retrieves the instructions position for a field and checks if it should be displayed in a specific position.

```twig
{% set instructionsPosition = craft.formie.getInstructionsPosition(field, form) %}

{% if instructionsPosition.shouldDisplay('below') %}
    <small>...</small>
    ...
```

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

### Listen for Date Picker Initialization

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Use the `afterInit` event to access the initialized Flatpickr instance and its options.

```javascript
// Fetch all Date fields - specifically the input. Events are bound on the input element
let $fields = document.querySelectorAll('[data-field-type="date-time"] input');

// For each field, bind on the `afterInit` event
$fields.forEach($field => {
    $field.addEventListener('afterInit', (e) => {
        let datePickerField = e.detail.datepicker;
        let options = e.detail.options;
    });
});
```

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

### Get Label Position

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/available-variables

Retrieves the label position for a field and checks if it should be displayed in a specific position.

```twig
{% set labelPosition = craft.formie.getLabelPosition(field, form) %}

{% if labelPosition.shouldDisplay('above') %}
    <label>...</label>
    ...
```

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

### Get Field Options

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/available-variables

Retrieves the render options for a specific field from the main options array.

```twig
{{ craft.formie.getFieldOptions(field) }}
```

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

### Create a Custom Formie Automation Integration

Source: https://verbb.io/craft-plugins/formie/docs/developers/custom-integration

Extend the `Automation` class to create a custom integration. Implement methods like `displayName`, `getIconUrl`, `getDescription`, `getSettingsHtml`, `getFormSettingsHtml`, `fetchFormSettings`, and `sendPayload` to define your integration's behavior.

```php
<?php
namespace modules\sitemodule;

use verbb\formie\base\Automation;
use verbb\formie\elements\Form;
use verbb\formie\elements\Submission;
use verbb\formie\models\IntegrationField;
use verbb\formie\models\IntegrationFormSettings;

use Craft;

class ExampleAutomation extends Automation
{
    public $url;

    public static function displayName(): string
    {
        return Craft::t('formie', 'Example Automation');
    }

    public function getIconUrl(): string
    {
        return Craft::$app->getAssetManager()->getPublishedUrl("@modules/mymodule/resources/icon.svg", true);
    }

    public function getDescription(): string
    {
        return Craft::t('formie', 'This is an example Automation integration.');
    }

    public function getSettingsHtml(): string
    {
        $variables = $this->getSettingsHtmlVariables();

        return Craft::$app->getView()->renderTemplate('path/to/settings', $variables);
    }

    public function getFormSettingsHtml($form): string
    {
        $variables = $this->getFormSettingsHtmlVariables($form);

        return Craft::$app->getView()->renderTemplate('path/to/form-settings', $variables);
    }

    public function fetchFormSettings()
    {
        // Fetch the form from our POST param
        $formId = Craft::$app->getRequest()->getParam('formId');
        $form = Formie::$plugin->getForms()->getFormById($formId);

        // Generate a new submission
        $submission = new Submission();
        $submission->setForm($form);

        // Populate the submission with fake data, for testing
        Formie::$plugin->getSubmissions()->populateFakeSubmission($submission);

        // Use Formie's function to generate a payload to send
        $payload = $this->generatePayloadValues($submission);
        $response = $this->getClient()->request('POST', $this->url, $payload);

        $json = Json::decode((string)$response->getBody());

        return new IntegrationFormSettings([
            'response' => $response,
            'json' => $json,
        ]);
    }

    public function sendPayload(Submission $submission): bool
    {
        // Generate a payload of values to send to the url
        $payload = $this->generatePayloadValues($submission);

        // Send the content to the URL
        $response = $this->getClient()->request('POST', $this->url, $payload);

        return true;
    }
}

```

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

### Import All Formie Forms

Source: https://verbb.io/craft-plugins/formie/docs/developers/console-commands

Imports all Formie form JSON files from a specified folder. Use the `--create` flag to create new forms instead of updating existing ones.

```bash
./craft formie/forms/import-all
```

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

### Form Submissions

Source: https://verbb.io/craft-plugins/formie/docs/developers/graphql

How to retrieve form submissions using the `formieSubmissions` query, with an example of the expected JSON response.

```APIDOC
## Retrieving Form Submissions

### Description
This section details how to query for form submissions using the `formieSubmissions` query. It includes an example of the query and the structure of the JSON response.

### GraphQL Query Example
```graphql
{
    formieSubmissions (form: "contactForm") {
        title

        ... on contactForm_Submission {
            yourName
            emailAddress
            message
        }
    }
}
```

### Response Example (JSON)
```json
{
    "data": {
        "formieSubmissions": [
            {
                "title": "2020-07-24 22:01:59",
                "yourName": "Peter Sherman",
                "emailAddress": "psherman@wallaby.com",
                "message": "Just wanted to say hi!"
            }
        ]
    }
}
```
```

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

### Get Submissions Related to an Entry

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/relations

Fetch an entry and then list all Formie submissions that are related to it using a reverse relation query.

```twig
{% set entry = craft.entries.id(2242).one() %}

Submissions related to {{ entry.title }}

{% for elementRelation in craft.formie.getSubmissionRelations(entry) %}
    {{ elementRelation.title }}
{% endfor %}
```

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

### Customize the AJAX Client

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

The `modifyAjaxClient` event allows customization of the XMLHttpRequest client used for Ajax submissions. For example, you can set `withCredentials` to `true`.

```javascript
let $form = document.querySelector('#formie-form-1');
$form.addEventListener('modifyAjaxClient', (e) => {
    e.detail.client.withCredentials = true;

    // ...
});
```

```jquery
$('#formie-form-1').on('modifyAjaxClient', function(e) {
    e.detail.client.withCredentials = true;

    // ...
});
```

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

### Configure Theme

Source: https://verbb.io/craft-plugins/formie/docs/get-started/configuration

Supply a nested array for the configuration form and fields should use when rendering. This allows for custom styling of form elements.

```php
'themeConfig' => [
    'form' => [
        'class' => 'border border-red-500',
    ],
    'field' => [
        'class' => 'uppercase',
    ],
],
```

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

### Listen for beforeApplyStencilDelete Event

Source: https://verbb.io/craft-plugins/formie/docs/developers/events

Triggered before a stencil deletion is applied. Useful for intercepting deletion actions.

```php
use verbb\formie\events\StencilEvent;
use verbb\formie\services\Stencils;
use yii\base\Event;

Event::on(Stencils::class, Stencils::EVENT_BEFORE_APPLY_STENCIL_DELETE, function(StencilEvent $event) {
    $stencil = $event->stencil;
    // ...
});
```

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

### Get User's Form Submissions

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/editing-submissions

Fetches all submissions for a specific form belonging to the currently logged-in user. Ensure `currentUser` is available.

```twig
{% set submissions = craft.formie.submissions.form('contactUs').email(currentUser.email).all() %}

{% for submission in submissions %}
    <a href="account/form/{{ submission.id }}">Edit {{ submission.title }}</a>
{% endfor %}
```

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

### Modify Name Field Prefix Options

Source: https://verbb.io/craft-plugins/formie/docs/developers/events

Add custom prefix options for the Name field. This example adds 'Mx.' as a new prefix option.

```php
use verbb\formie\events\ModifyNamePrefixOptionsEvent;
use verbb\formie\fields\subfields\NamePrefix;
use yii\base\Event;

Event::on(NamePrefix::class, NamePrefix::EVENT_MODIFY_PREFIX_OPTIONS, function(ModifyNamePrefixOptionsEvent $event) {
    $event->options[] = ['label' => Craft::t('formie', 'Mx.'), 'value' => 'mx'];
});
```

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

### Listen to beforeInit Event for Date Fields (JavaScript)

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Fires before the Flatpickr date picker is initialized for a Date field. Use this to modify Flatpickr options, such as setting minimum or maximum dates.

```javascript
// Fetch all Date fields - specifically the input. Events are bound on the input element
let $fields = document.querySelectorAll('[data-field-type="date-time"] input');

// For each field, bind on the `beforeInit` event
$fields.forEach($field => {
    $field.addEventListener('beforeInit', (e) => {
        let datePickerField = e.detail.datepicker;
        let options = e.detail.options;

        // Modify any Flatpickr options
        e.detail.options.minDate = '2021-06-03';
    });
});
```

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

### Modify HTML Purifier Config

Source: https://verbb.io/craft-plugins/formie/docs/developers/events

Customize the HTML Purifier configuration for the HTML field. This example adds a custom attribute 'data-type' to span elements.

```php
use verbb\formie\events\ModifyPurifierConfigEvent;
use verbb\formie\fields\Html;
use HTMLPurifier_AttrDef_Text;
use yii\base\Event;

Event::on(Html::class, Html::EVENT_MODIFY_PURIFIER_CONFIG, function(ModifyPurifierConfigEvent $event) {
    $event->config->getHTMLDefinition(true)->addAttribute('span', 'data-type', new HTMLPurifier_AttrDef_Text());
});
```

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

### Formie Integration Template Usage

Source: https://verbb.io/craft-plugins/formie/docs/developers/custom-integration

Use `getFormSettings()` to retrieve cached settings in your templates. Call `fetchFormSettings()` to bypass the cache and get fresh data.

```twig
{% set handle = integration.handle %}
{% set formSettings = integration.getFormSettings().getSettings() %}

<integration-form-settings handle="{{ handle }}" :form-settings="{{ formSettings | json_encode }}" inline-template>
// ...
</integration-form-settings>
```

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

### Global Plugin Theme Configuration (PHP)

Source: https://verbb.io/craft-plugins/formie/docs/theming/theme-config

Define default theme configurations at the global plugin level using PHP. This method has the lowest priority and can be overridden by other methods.

```php
<?php

return [
    'themeConfig' => [
        // Remove all of Formie's classes by default
        'resetClasses' => true,

        // For the field `<form>` element, change the tag and add attributes
        'form' => [
            'attributes' => [
                'class' => 'p-4 w-full mb-4',
                'tag' => 'div',
            ],
        ],

        // For the main field element
        'field' => [
            'attributes' => [
                'class' => 'p-4 w-full mb-4',
            ],
        ],

        // Specifically for a single-line-text field, we want the label uppercased
        'singleLineText' => [
            'fieldLabel' => [
                'attributes' => [
                    'class' => 'uppercase',
                ],
            ],
        ],
    ],
];
```

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

### Query Forms by Title

Source: https://verbb.io/craft-plugins/formie/docs/getting-elements/form-queries

Narrows query results based on the forms' titles using wildcard matching. Supports starts with, ends with, contains, and not contains.

```Twig
{# Fetch forms with a title that contains "Foo" #}
{% set forms = craft.formie.forms()
    .title('*Foo*')
    .all() %}
```

```PHP
// Fetch forms with a title that contains "Foo"
$forms = \verbb\formie\elements\Form::find()
    ->title('*Foo*')
    ->all();
```

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

### Listen for Form Initialization with jQuery

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Use jQuery to listen for the `onFormieInit` event, which fires when Formie initializes a visible form. Event details include the Formie instance, form element, and form ID.

```javascript
$(document).on('onFormieInit', function(e) {
    // The instance of the Formie JS library
    let Formie = e.detail.formie;

    // The `<form>` HTML element
    let $form = e.detail.$form;

    // The instance of the Formie form class, which encapsulates most logic
    let form = e.detail.form;

    // The `formId` of the form, used as a unique identifier
    let formId = e.detail.formId;

    // ...
});
```

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

### Modify Nested Name Field Layout

Source: https://verbb.io/craft-plugins/formie/docs/developers/events

Customize the layout of nested fields within a Name field. This example changes the label of the 'lastName' sub-field to 'Surname'.

```php
use verbb\formie\events\ModifyNestedFieldLayoutEvent;
use verbb\formie\fields\Name;
use yii\base\Event;

Event::on(Name::class, Name::EVENT_MODIFY_NESTED_FIELD_LAYOUT, function(ModifyNestedFieldLayoutEvent $event) {
    // Lookup the last name sub-field. We can no longer rely on a static order
    $lastName = $event->fieldLayout->getFieldByHandle('lastName');

    // Modify the `lastName` field - a `SingleLineText` field.
    $lastName->label = 'Surname';
});
```

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

### Create a Custom Address Provider Integration

Source: https://verbb.io/craft-plugins/formie/docs/developers/custom-integration

Extend the `AddressProvider` class to create a custom address provider. Implement methods such as `displayName`, `getIconUrl`, `getDescription`, `getSettingsHtml`, `getFrontEndHtml`, and `getFrontEndJsVariables` to define its functionality.

```php
<?php
namespace modules\sitemodule;

use verbb\formie\base\AddressProvider;
use verbb\formie\elements\Form;
use verbb\formie\elements\Submission;

use Craft;

class ExampleAddressProvider extends AddressProvider
{
    public static function displayName(): string
    {
        return Craft::t('formie', 'Example Address Provider');
    }

    public function getIconUrl(): string
    {
        return Craft::$app->getAssetManager()->getPublishedUrl("@modules/mymodule/resources/icon.svg", true);
    }

    public function getDescription(): string
    {
        return Craft::t('formie', 'This is an example address provider.');
    }

    public function getSettingsHtml(): string
    {
        $variables = $this->getSettingsHtmlVariables();

        return Craft::$app->getView()->renderTemplate('path/to/settings', $variables);
    }

    public function getFrontEndHtml($field, $options): string
    {
        return '<input type="hidden" />';
    }

    public function getFrontEndJsVariables(Form $form, $field = null)
    {
        $src = Craft::$app->getAssetManager()->getPublishedUrl('path-to-js.js', true);
        $onload = 'new MyCustomFunction();';

        return [
            'src' => $src,
            'onload' => $onload,
        ];
    }
}
```

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

### Modify Phone Field Initialization Options

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Use the `beforeInit` event to modify options for the phone number library before it initializes. For example, disable the fullscreen popup.

```javascript
// Fetch all Phone fields - specifically the input. Events are bound on the input element
let $fields = document.querySelectorAll('[data-field-type="phone"] input');

// For each field, bind on the `beforeInit` event
$fields.forEach($field => {
    $field.addEventListener('beforeInit', (e) => {
        let phoneCountryField = e.detail.phoneCountry;
        let options = e.detail.options;

        // Modify any options
        e.detail.options.useFullscreenPopup = false;
    });
});
```

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

### Get Current, Next, and Previous Pages

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/rendering-pages

Retrieve the current, next, or previous page objects for multi-page forms. These functions return `null` if there is no corresponding page.

```twig
{% set currentPage = form.getCurrentPage() %}
{% set nextPage = form.getNextPage() %}
{% set prevPage = form.getPreviousPage() %}
```

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

### Listen for Table init event

Source: https://verbb.io/craft-plugins/formie/docs/developers/javascript-api

Bind an event listener to the 'init' event on table fields to execute code before the table is initialized. Access the table field instance.

```javascript
// Fetch all Table fields
let $fields = document.querySelectorAll('[data-field-type="table"]');

// For each field, bind on the `init` event
$fields.forEach($field => {
    $field.addEventListener('init', (e) => {
        let tableField = e.detail.table;
    });
});
```

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

### Query Submissions

Source: https://verbb.io/craft-plugins/formie/docs/template-guides/available-variables

Use `craft.formie.submissions()` to retrieve submission objects. You can filter submissions by parameters like `formId` and `limit`. Use `.all()` to get multiple submissions.

```twig
{% set submissions = craft.formie.submissions({ formId: 123, limit: 10 }).all() %}
```

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

### Fetch a Form by Handle

Source: https://verbb.io/craft-plugins/formie/docs/getting-elements/form-queries

Create a form query, set the 'handle' parameter to filter by a specific form's handle, and then use `.one()` to fetch a single form. This is useful for displaying a specific form.

```twig
{# Create a form query with the 'handle' parameter #}
{% set formQuery = craft.formie.forms()
    .handle('contactForm') %}

{# Fetch the Form #}
{% set form = formQuery.one() %}

{# Display their contents #}
<p>{{ form.title }}</p>
```

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

### Modify Email Field Unique Query

Source: https://verbb.io/craft-plugins/formie/docs/developers/events

Customize the database query used to check for unique email submissions. This example limits uniqueness to one per day.

```php
use verbb\formie\events\ModifyEmailFieldUniqueQueryEvent;
use verbb\formie\fields\Email;
use yii\base\Event;

Event::on(Email::class, Email::EVENT_MODIFY_UNIQUE_QUERY, function(ModifyEmailFieldUniqueQueryEvent $event) {
    $query = $event->query;
    $field = $event->field;
    // ...

    // e.g. change the query to only look at today's submissions, to allow only one per day.
    $event->query->andWhere('DATE(e.dateCreated) = UTC_DATE()');
});
```
Tokens:
Raw