Tall Forms Laravel Package

Getting Started

First Steps

1. Installation

   composer require tanthammar/tall-forms
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="Tanthammar\TallForms\TallFormsServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Tanthammar\TallForms\TallFormsServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Basic Setup

   • Register the Livewire component in your blade:

     @livewire('tall-forms::form', ['model' => \App\Models\User::class])
     

   • Define a form in a dedicated class (e.g., app/Http/Livewire/Forms/UserForm.php):

     use Tanthammar\TallForms\Contracts\Form;
     
     class UserForm implements Form
     {
         public function fields(): array
         {
             return [
                 'name' => 'text',
                 'email' => 'email',
                 'password' => 'password',
             ];
         }
     }
     

3. First Use Case

   • Create a form for a User model with validation:

     public function fields(): array
     {
         return [
             'name' => [
                 'type' => 'text',
                 'label' => 'Full Name',
                 'rules' => 'required|min:3',
             ],
             'email' => [
                 'type' => 'email',
                 'label' => 'Email',
                 'rules' => 'required|email',
             ],
         ];
     }
     

Implementation Patterns

Core Workflows

1. Dynamic Form Generation

   • Use fields() method to define fields dynamically (e.g., fetch from a database or API).
   • Example: Fetch fields from a config file or Eloquent model attributes:

     public function fields(): array
     {
         return collect(config('form.fields'))->mapWithKeys(function ($field) {
             return [$field['name'] => $field];
         })->toArray();
     }
     

2. Reusable Form Components

   • Extend the base form class for shared logic:

     class BaseForm implements Form
     {
         public function commonFields(): array
         {
             return [
                 'created_at' => [
                     'type' => 'date',
                     'hidden' => true,
                 ],
             ];
         }
     }
     

3. Integration with Livewire

   • Use wire:model for real-time updates:

     <x-tall-forms::input name="email" wire:model="form.email" />
     

   • Handle submission in a Livewire component:

     public function submit()
     {
         $this->validate($this->form->rules());
         $this->form->save();
     }
     

4. Nested and Array Fields

   • Define nested fields for complex structures (e.g., addresses):

     public function fields(): array
     {
         return [
             'addresses' => [
                 'type' => 'repeatable',
                 'fields' => [
                     'street' => 'text',
                     'city' => 'text',
                 ],
             ],
         ];
     }
     

5. File Uploads

   • Configure file upload fields with storage rules:

     public function fields(): array
     {
         return [
             'avatar' => [
                 'type' => 'file',
                 'rules' => 'nullable|image|mimes:jpeg,png|max:2048',
                 'storage' => 'public',
             ],
         ];
     }
     

Advanced Patterns

1. Custom Field Types

   • Extend the base field types by creating a custom component:

     // app/Http/Livewire/CustomFields/CustomSelect.php
     public function render()
     {
         return view('livewire.custom-fields.custom-select', [
             'name' => $this->name,
             'options' => $this->options,
         ]);
     }
     

   • Register the component in config/tall-forms.php:

     'custom_fields' => [
         'custom_select' => \App\Http\Livewire\CustomFields\CustomSelect::class,
     ],
     

2. Form Events

   • Listen to form events (e.g., saving, saved) in your Livewire component:

     protected $listeners = ['form.saving' => 'onSaving'];
     
     public function onSaving()
     {
         // Pre-save logic
     }
     

3. Conditional Fields

   • Show/hide fields based on user input:

     public function fields(): array
     {
         return [
             'is_admin' => [
                 'type' => 'checkbox',
                 'label' => 'Admin User',
             ],
             'admin_fields' => [
                 'type' => 'conditional',
                 'condition' => ['is_admin', '==', true],
                 'fields' => [
                     'role' => 'select',
                 ],
             ],
         ];
     }
     

4. Multi-Step Forms

   • Use tabs or steps to break forms into logical sections:

     <x-tall-forms::tabs>
         <x-slot name="step1">
             <x-tall-forms::input name="name" />
         </x-slot>
         <x-slot name="step2">
             <x-tall-forms::input name="email" />
         </x-slot>
     </x-tall-forms::tabs>
     

Gotchas and Tips

Common Pitfalls

1. Validation Rules Not Applying

   • Ensure rules are defined in the fields() array and match Laravel's validation syntax.
   • Debug with:

     $this->validate($this->form->rules());
     

2. File Uploads Not Working

   • Verify the storage path exists and is writable.
   • Check rules for correct mime types and size limits.

3. Conditional Fields Not Triggering

   • Ensure the condition array follows [field, operator, value] format (e.g., ['is_admin', '==', true]).
   • Use wire:model.live for real-time updates:

     <input wire:model.live="is_admin" type="checkbox">
     

4. Nested Fields Not Saving

   • For repeatable fields, ensure the model uses hasMany or morphMany relationships.
   • Example model:

     public function addresses()
     {
         return $this->hasMany(Address::class);
     }
     

5. Livewire State Not Persisting

   • Avoid resetting the form state manually; let TallForms handle it.
   • If needed, override resetForm() in your Livewire component.

Debugging Tips

1. Log Field Data

   • Dump the form data in submit():

     dd($this->form->all());
     

2. Check Config Overrides

   • Verify config/tall-forms.php for customizations (e.g., default_locale, storage_path).

3. Inspect Blade Components

   • Use @dd($this) inside a custom component to debug props.

4. Clear Cached Views

   • If changes aren’t reflecting, run:

     php artisan view:clear
     

Extension Points

1. Custom Field Components

   • Place custom components in resources/views/vendor/tall-forms/fields/ or app/View/Components/TallForms.

2. Override Default Templates

   • Publish and modify views:

     php artisan vendor:publish --tag="tall-forms-views"
     

3. Hook into Form Lifecycle

   • Use FormEvents to intercept creating, updating, or deleting:

     event(new FormCreating($this->form));
     

4. Add Custom JavaScript

   • Extend the form with Alpine.js or vanilla JS:

     <script>
         document.addEventListener('livewire:init', () => {
             Livewire.on('form-updated', (data) => {
                 console.log('Form updated:', data);
             });
         });
     </script>
     

Performance Tips

1. Lazy-Load Fields

   • For large forms, load fields dynamically:

     public function fields(): array
     {
         return collect(request('fields', []))->mapWithKeys(function ($field) {
             return [$field => $this->getFieldDefinition($field)];
         })->toArray();
     }
     

2. Debounce Validation

   • Add debounce to inputs to reduce server load:

     <x-tall-forms::input name="email" debounce="500" />
     

3. Use wire:ignore for Heavy Components

   • Offload processing to the server:

     <div wire:ignore>
         <x-tall-forms::rich-text name="description" />
     </div>