README

Livewire Forms

This addon provides a powerful framework to use Statamic forms with Laravel Livewire. No more submitting your form with AJAX or dealing with funky client-side validation libraries. Livewire Forms is a powerhouse that will make your life soooo much easier!

Features

Use your Statamic form blueprints as a form builder
Real-time validation with fine-grained control over each field
No need for a client-side form validation library
One source of truth for your validation rules
Spam protection with Google reCAPTCHA v2 and honeypot field
Support for display conditions set in your form blueprint
Multi-site support; translate your form display labels, instructions, placeholders, etc.
Configured and styled form views

Installation

Install the addon using Composer:

composer require aerni/livewire-forms

Publish the config of the package (optional):

php please vendor:publish --tag=livewire-forms-config

Manually bundling Livewire and Alpine

If you are manually bundling Livewire and Alpine, you will also need to import the Livewire Forms script:

import { Livewire, Alpine } from '../../vendor/livewire/livewire/dist/livewire.esm';
import Clipboard from '@ryangjchandler/alpine-clipboard'
+ import "../../vendor/aerni/livewire-forms/resources/dist/js/livewire-forms";

Alpine.plugin(Clipboard)

Livewire.start()

Then, add the {{ livewire:styles }} and {{ livewire:scriptConfig }} tags to your layout:

<html>
    <head>
        <!-- Antlers -->
        {{ livewire:styles }}

        <!-- Blade -->
        @livewireStyles
    </head>
    <body>
        <!-- Antlers -->
        {{ livewire:scriptConfig }}

        <!-- Blade -->
        @livewireScriptConfig
    </body>
</html>

At this point, you can safely remove the livewire-forms.js script from your form views, as it is now included in your bundle:

- @assets
-     <script type="module" src="/vendor/livewire-forms/js/livewire-forms.js"></script>
- @endassets

Commands

There are a number of helpful commands to help you create views, themes and components:

Getting started

Prerequisite

The views of this addon are styled with Tailwind CSS and @tailwindcss/forms. However, you are free to change the views however you please.

Run the setup command

Go ahead and run the livewire-forms:setup command in your console. It will guide you through creating your first view and theme. Optionally, you may also create a component for complete control of your form.

php please livewire-forms:setup

Render the form

Add the Livewire form component to your template and provide the handle of the Statamic form.

<!-- Antlers -->
{{ livewire:form handle="contact" }}

<!-- Blade -->
<livewire:form handle="contact">

You can also dynamically render a form that was selected via Statamic's Form fieldtype:

<!-- Antlers -->
{{ livewire:form :handle="field:handle" }}

<!-- Blade -->
<livewire:form :handle="field:handle">

Use the view and theme parameters if you want to use a view or theme that is different from the defaults defined in config/livewire-forms.php.

<!-- Antlers -->
{{ livewire:form :handle="field:handle" view="contact" theme="regular" }}

<!-- Blade -->
<livewire:form :handle="field:handle" view="contact" theme="regular">

Available Properties

Views

Views are the entry point of your forms. You may use the same view for each form.

Creating a view

Use the livewire-forms:view command to create a new view:

php please livewire-forms:view

Autoloading

Views are autoloaded by the handle of a form. In the example below, it will try to load the contact.blade.php view. If it doesn't exist, it will fall back to the default view defined in config/livewire-forms.php.

{{ livewire:form handle="contact" }}

Blade Directives

There are a couple of blade directives you may use in your form views. The directives are aware of the form's theme and will render the views accordingly.

Customization Example

Sometimes you need more control over the markup of your form. Rather than relying on the form's blueprint, you may decide to go fully custom and render individual fields using the @formField directive.

@formField('name')

You may also add or override field properties using an array as the second argument.

@formField('name', [
    'display' => 'Your Name',
    'tooltip' => 'Please enter your full name'
])

You can then access the properties in the field's view.

{{ $field->display }}
{{ $field->tooltip }}

Themes

Themes allow you to fully customize each individual form view. You may have any number of themes.

Creating a theme

Use the livewire-forms:theme command to create a new theme:

php please livewire-forms:theme

Autoloading

Themes are autoloaded by the handle of a form. In the example below, it will try to load the views of the contact theme. If the theme doesn't exist, it will fall back to the default theme defined in config/livewire-forms.php. If a single view of the selected theme doesn't exist, it will fall back to the default theme for that particular view.

{{ livewire:form handle="contact" }}

Good to know: Future releases of this addon will likely introduce breaking changes to your views. In that case, you will have to manually update your views according to the changes.

Field Views

By default, each field will load the view by its type. For example, a subscription field of type: radio will load the radio.blade.php view.

Sometimes you may want to load a different view for a given field, like a fancy radio button group for selecting a subscription. Field views are autoloaded by the field's handle. In this example, you can simply create a subscription.blade.php view under the theme's fields folder to autoload your custom view.

You may manually override a field's view by adding view: {the_name_of_the_view} to the field's config in the blueprint.

Components

Sometimes, you need more control over your form. For instance, if you want to dynamically populate a select field's options. There are a couple of concepts that help you customize your form experience.

Creating a component

Get started by creating a new component. The following example will create a new form component in app/Livewire/ContactForm.php

php please livewire-forms:component ContactForm

Autoloading

Custom components are autoloaded by matching the class name with the form's handle. In the example below, it will try to load the App\Livewire\ContactForm.php component. If this component doesn't exist, it will fall back to the default form component.

<!-- Antlers -->
{{ livewire:form handle="contact" }}

<!-- Blade -->
<livewire:form handle="contact">

Note: For the autoloading magic to work, the component's name needs to end with Form, e.g., ContactForm.php.

Explicit Loading

You can also explicitly load a custom component by name like you would with any other Livewire component. This is necessary if you need to pass additional custom properties to the component.

<!-- Antlers -->
{{ livewire:contact-form my-custom-prop="value" }}

<!-- Blade -->
<livewire:contact-form my-custom-prop="value">

Field Models

Each Statamic fieldtype is mapped to a Livewire Forms field model. Models are responsible for generating a field's properties like view, display, instructions, options, and so on. You can find the default mappings in config/livewire-forms.php.

For instance, all the fields of type \Statamic\Fieldtypes\Select::class are bound to the \Aerni\LivewireForms\Fields\Select::class model. A field property is created for each model method ending with Property, e.g. optionsProperty() will generate an options property.

To change a field's default model, simply change the binding in the models property in your component:

protected array $models = [
    \Statamic\Fieldtypes\Select::class => \App\Fields\Select::class,
];

If you want to change a model for a specific field only, simply use the field's handle as the key instead:

protected array $models = [
    'products' => \App\Fields\SelectProduct::class,
];

Tip: You may change the default bindings in config/livewire-forms.php. If you have a fieldtype that's not supported by this addon, simply create a new model and add the binding to the config.

Hooks

There are a couple of hooks that let you modify fields and submission data at various lifecycle steps.

Mounted Fields

Use this hook to modify the fields after they are mounted.

public function mountedFields(Collection $fields): void
{
    $fields->get('name')->display('Your name');
}

Form Submitted

Use this hook to modify the form submission before it is processed by Statamic.

public function formSubmitted(Submission $submission): void
{
    $title = $submission->augmentedValue('entry')->value()->title;

    $submission->set('entry_title', $title);
}

Events

This addon dispatches the following Events.

Form Submitted

The form-submitted Livewire and FormSubmitted Statamic event is dispatched right after the Form Submitted hook. You can listen to this event as follows.

Livewire

@script
<script>
    $wire.on('form-submitted', () => {
        //
    });
</script>
@endscript

Statamic Statamic\Events\FormSubmitted

public function handle(FormSubmitted $event)
{
    $event->submission; // The Submission object
}

Customization Example

In the following example we want to dynamically generate the options of a select field based on the entries of a Statamic collection. We also want to change the view of the field because the design needs to be different to a regular select field. There are two ways to achieve our task. We can either create a custom field model or use the hydratedFields callback. Choose whichever route feels better to you.

Using a custom field model

We start by creating a new SelectProduct field model class that extends the default Select model class. We then override the optionsProperty method to return our options from a collection. We also assign a different view using the $view class property.

namespace App\Fields;

use Aerni\LivewireForms\Fields\Select;
use Statamic\Facades\Entry;

class SelectProduct extends Select
{
    protected string $view = 'select_product';

    public function optionsProperty(): array
    {
        return Entry::whereCollection('products')
            ->mapWithKeys(fn ($product) => [$product->slug() => $product->get('title')])
            ->all();
    }
}

Next, we need to tell the form which field we want to use the SelectProduct model for. In our case, we only want to use the SelectProduct model for the select field with the handle products.

namespace App\Livewire;

use Aerni\LivewireForms\Livewire\Form;

class ContactForm extends Form
{
    protected array $models = [
        'products' => \App\Fields\SelectProduct::class,
    ];
}

Using the mountedFields hook

Instead of defining a new field model, we can also achieve the same thing using the mountedFields hook.

namespace App\Livewire;

use Aerni\LivewireForms\Livewire\Form;

class ContactForm extends Form
{
    public function mountedFields(Collection $fields): void
    {
        $options = Entry::whereCollection('products')
            ->mapWithKeys(fn ($product) => [$product->slug() => $product->get('title')])
            ->all();

        $fields->get('products')
            ->options($options)
            ->view('select_product');
    }
}

Render the component

Lastly, we need to render our new ContactForm component in the template.

<!-- Antlers -->
{{ livewire:form handle="contact" }}

<!-- Blade -->
<livewire:form handle="contact">

Validation

Validation Rules

You can use any validation rule you want. Simply add it to the field in the form blueprint or use the blueprint builder in the CP.

To validate against the value of another field, you need to get its value like in the following example:

validate:
  - 'required_if:fields.newsletter.value,true'

Real-time Validation

Real-time validation works out of the box by updating the field's value on change event. You may override this behavior by setting the wire_model parameter in the field's config.

tabs:
  main:
    display: Main
    sections:
      -
        fields:
          -
            handle: email
            field:
              type: text
              wire_model: live.debounce.150ms
              validate:
                - required
                - email

To use Livewire's default behavior and defer all network requests until the form is submitted, you may set wire_model: defer.

Validation Messages

You can customize the validation messages of your fields by creating a custom form component and using either of the two methods below.

Note: Make sure to add data in front of the field's handle.

Using the `$messages` property

protected $messages = [
    'fields.name.value.required' => 'What is your name, darling?',
];

Using the `messages()` method

protected function messages(): array
{
    return [
        'fields.name.value.required' => 'What is your name, darling?',
    ];
}

Localization

There are a few default message strings, like the submit button label and success message that you might want to change. You can change the messages globally or on a per-form level.

Globally

Publish the language files and change whatever message you'd like:

php artisan vendor:publish --tag=livewire-forms-translations

Per Form

Create a file called livewire-forms.php for each of your localizations, e.g., resources/lang/en/livewire-forms.php.
Create an array with the handle of each form for which you want to change a message for.
Use the same keys that are used in the global language files. Note, that the messages in this file will take precedence over the messages in the global language file.

return [

    'contact' => [
        'submit_button_label' => 'Contact now',
        'success_message' => 'Thanks for contacting us. We will be in touch.',
        'error_message' => 'There was an error with your submission:|There were :count errors with your submission:',
    ],

    'newsletter' => [
        'submit_button_label' => 'Signup now',
    ],

];

Translating sections and fields

You can translate your field display labels, instructions, options, and placeholders using JSON files. Create a translation file for each language, e.g. resources/lang/de.json.

Example

Form Blueprint

tabs:
  main:
    display: Main
    sections:
      -
        display: Subscription
        instructions: 'Choose your subscription below'
        fields:
          -
            handle: subscription
            field:
              display: Subscription
              placeholder: 'Which subscription do you want?'

Translation File

{
    "Subscription": "Abo",
    "Choose your subscription below": "Wähle dein Abo",
    "Which subscription do you want?": "Welches Abo möchtest du?",
}

Captcha Fieldtype

This addon comes with a Captcha fieldtype that lets you add a Google reCAPTCHA v2 (checkbox) captcha to your form. The Captcha fieldtype is available in the form blueprint builder like any other fieldtype.

Note: Make sure to add your captcha key and secret in your .env file.

License

Livewire Forms is commercial software but has an open-source codebase. If you want to use it in production, you'll need to buy a license from the Statamic Marketplace.

Livewire Forms is NOT free software.

Credits

Developed by Michael Aerni

aerni / livewire-forms

Maintainers

Details

README

Livewire Forms

Features

Installation

Manually bundling Livewire and Alpine

Commands

Getting started

Prerequisite

Run the setup command

Render the form

Available Properties

Views

Creating a view

Autoloading

Blade Directives

Customization Example

Themes

Creating a theme

Autoloading

Field Views

Components

Creating a component

Autoloading

Explicit Loading

Field Models

Hooks

Mounted Fields

Form Submitted

Events

Form Submitted

Customization Example

Using a custom field model

Using the mountedFields hook

Render the component

Validation

Validation Rules

Real-time Validation

Validation Messages

Using the $messages property

Using the messages() method

Localization

Globally

Per Form

Translating sections and fields

Example

Captcha Fieldtype

License

Credits

Using the `$messages` property

Using the `messages()` method