Getting Started

Minimal Setup

Installation

composer require allyoullneed/livewire-forms

Publish the config (if needed):

php artisan vendor:publish --provider="Allyoullneed\LivewireForms\LivewireFormsServiceProvider"

First Use Case
- Create a Statamic form blueprint (e.g., contact_form).
- Render it in a Blade view:
```
<livewire:statamic-form in="contact_form" />
```
- The form will auto-render fields based on the blueprint (text, email, textarea, etc.).
Key Files to Review
- config/livewire-forms.php (customization options like default validation rules).
- resources/views/vendor/livewire-forms/ (default Blade templates for overrides).

Implementation Patterns

Core Workflow

Blueprint-Driven Forms
- Define fields in Statamic’s Form Builder (e.g., contact_form).
- The package maps blueprint fields to Livewire components (e.g., TextInput, EmailInput).
- Example blueprint:
```
fields:
  name:
    type: text
    required: true
  message:
    type: textarea
```

Livewire Integration

Validation: Leverage Livewire’s $rules in a custom component:

public $rules = [
    'name' => 'required|min:3',
    'message' => 'required|max:1000',
];

Submission Handling: Override submit() in a custom Livewire class:

public function submit()
{
    $validated = $this->validate();
    // Process data (e.g., save to DB or send email)
    session()->flash('success', 'Form submitted!');
    $this->reset();
}

Component Customization
- Extend default components (e.g., TextInput) by publishing views:
```
php artisan vendor:publish --tag=livewire-forms-views
```
- Override a field template (e.g., resources/views/vendor/livewire-forms/fields/text.blade.php):
```
<input type="text" wire:model="state.{{ $field->handle }}" class="my-custom-class">
```

Dynamic Form Rendering

Pass dynamic data to the form:

<livewire:statamic-form
    in="contact_form"
    :data="['default_name' => 'John Doe']"
/>

Advanced Patterns

Multi-Step Forms

Use Livewire’s currentStep property to manage steps:

public $currentStep = 1;
public function nextStep() { $this->currentStep++; }

Conditionally render steps in Blade:

@if($currentStep === 1)
    <livewire:statamic-form in="contact_form" fields="name,email" />
@endif

Reusable Form Logic

Create a base Livewire class for shared form behavior:

class BaseForm extends Component
{
    public function save()
    {
        // Shared logic (e.g., logging, analytics)
    }
}

Extend it in your form component:

class ContactForm extends BaseForm { ... }

Conditional Fields
- Use Statamic’s conditional field settings in blueprints:
```
fields:
  newsletter:
    type: checkbox
    conditional:
      on: subscribe
      fields: email
```
- The package handles dynamic field visibility via Livewire.

Gotchas and Tips

Pitfalls

Blueprint Mismatches
- Issue: Fields in the blueprint don’t render.
- Fix: Ensure the blueprint handle matches the in attribute (case-sensitive).
- Debug: Check php artisan statamic:blueprints for typos.

Livewire State Persistence

Issue: Form data resets on page refresh.

Fix: Use wire:preserve or store data in session:

protected $listeners = ['refreshForm' => 'loadData'];
public function loadData() { $this->state = session('form_data'); }

Validation Conflicts

Issue: Blueprint validation overrides Livewire rules.

Fix: Disable blueprint validation in config:

'validation' => [
    'use_blueprint_rules' => false,
],

Or merge rules in submit():

$this->validate([
    'name' => ['required', 'min:3'], // Override blueprint rules
]);

Asset Loading
- Issue: Custom CSS/JS not loading for form fields.
- Fix: Publish assets and include them in your layout:
```
@livewireStyles
@livewireScripts
```

Debugging Tips

Log Field Data

Dump the form state in submit():

dd($this->state); // Inspect all submitted data

Check Livewire Events

Listen for form events in your component:

protected $listeners = [
    'form.submitted' => 'handleSubmission',
];

Blueprint Validation Errors
- Enable debug mode in config:
```
'debug' => true,
```
- Check Laravel logs for validation messages.

Extension Points

Custom Field Types

Create a new field component (e.g., RatingField):

class RatingField extends Field
{
    public function render()
    {
        return view('livewire-forms.fields.rating', ['field' => $this]);
    }
}

'fields' => [
    'rating' => \App\LivewireForms\Fields\RatingField::class,
],

Form Events

Dispatch custom events for frontend JS:

$this->dispatch('form-validated', data: $this->state);

Listen in Alpine.js:

window.addEventListener('form-validated', event => {
    console.log(event.detail.data);
});

Statamic Entry Integration

Save form submissions to a Statamic collection:

use Statamic\Facades\Entry;

public function submit()
{
    $validated = $this->validate();
    Entry::create([
        'collection' => 'contacts',
        'data' => $validated,
    ]);
}

Pro Tips

Use wire:ignore for Non-Interactive Elements Improve performance by excluding static elements:
```
<div wire:ignore>
    <p>Terms and conditions...</p>
</div>
```
Leverage Livewire’s wire:model.lazy For non-immediate validation (e.g., on blur):
```
<input wire:model.lazy="state.name">
```

Cache Blueprint Data Reduce Statamic API calls by caching blueprints:

public function mount()
{
    $this->blueprint = cache()->remember(
        "livewire-forms:{$this->formHandle}",
        now()->addHours(1),
        fn() => Statamic::blueprints()->get($this->formHandle)
    );
}

Livewire Forms Laravel Package