Eloquent

# Introduction

The Zinq Form Builder takes form creation to the next level by seamlessly integrating with Eloquent Models. With this approach, the Form Builder automatically scans your model’s attributes and generates the form structure for you. This method makes building forms even faster and more efficient, perfect for CRUD operations and beyond.

# Usage

To integrate a form into a Livewire component, you need to:

1. Create the EloquentForm class and define Eloquent model,
2. Create the form data property in your Livewire component,
3. Handle the form submission using a method in your Livewire component.

use Mattbit\Zinq\Form\EloquentForm;

...

return EloquentForm::make(Customer::class);

use Livewire\Component;
use Mattbit\Zinq\Form\EloquentForm;

class CreateCustomer extends Component
{
    public array $data = [];

    private function form(): Form
    {
        return EloquentForm::make(Customer::class);
    }

    public function save(): void
    {
        // The $this->data property contains the form data
    }

    public function render(): string
    {
        return view('livewire.create-customer', ['form' => $this->form()]);
    }
}

# How it works

The FormBuilder generates an HTML form based on an Eloquent model by inspecting the model’s database table schema. Regardless of whether the input is a reference to the model’s class or an instance of an existing model, the FormBuilder retrieves all columns from the corresponding table along with their types. It then maps these columns to specific form elements, such as text inputs, checkboxes, or select dropdowns, based on the column types and their constraints. This allows for dynamic form generation tailored to the underlying database structure.

# Primary Key

The FormBuilder automatically detects the primary key of the model and excludes it from the form structure. This is because the primary key is typically an auto-incrementing integer and is not meant to be edited by the user.

# Timestamps

The FormBuilder also excludes the created_at and updated_at columns from the form structure. These columns are automatically managed by the database and should not be modified by the user.

# Email and Password Fields

If the column name contains the word email or password , the FormBuilder automatically generates the appropriate form element. For example, a column named email will be represented as an email input field, while a column named password will be represented as a password input field.

# Validation

The Zinq Form Builder provides a simple way to validate form data. You can define validation rules using the setRules method.

use Mattbit\Zinq\Form\EloquentForm;

...

return EloquentForm::make(Customer::class)
    ->setRules([
        'name' => 'required|string|max:255',
        'email' => 'required|email',
    ]);

use Livewire\Component;
use Mattbit\Zinq\Form\EloquentForm;

class CreateCustomer extends Component
{
    public array $data = [];

    private function form(): Form
    {
        return EloquentForm::make(Customer::class)
            ->setRules([
                'name' => 'required',
                'email' => 'required|email',
            ]);
    }

    public function save(): void
    {
        // The $this->data property contains the form data
    }

    public function render(): string
    {
        return view('livewire.create-customer', ['form' => $this->form()]);
    }
}

# Customization

# Pre-filling form data

You can pre-fill form data by setting the initial values in the $data property of your Livewire component. This is useful when editing an existing record.

Form Builder provides data method which returns the form data with the model attributes. You can use this method to pre-fill the form data.

public array $data = [];

public function mount(Customer $customer): void
{
    // Or you can set the initial values dynamically in the mount method
    $this->data = $this->form()->data($customer);
}

private function form(): Form
{
    return EloquentForm::make(Customer::class);
}

# Inline elements

By default, form elements are displayed vertically. You can display them inline by using the inline method.

use Mattbit\Zinq\Form\EloquentForm;

...

return EloquentForm::make(Customer::class)
    ->inline();

use Livewire\Component;
use Mattbit\Zinq\Form\EloquentForm;

class CreateCustomer extends Component
{
    public array $data = [];

    private function form(): Form
    {
        return EloquentForm::make(Customer::class)
            ->inline();
    }

    public function save(): void
    {
        // The $this->data property contains the form data
    }

    public function render(): string
    {
        return view('livewire.create-customer', ['form' => $this->form()]);
    }
}

# Controlling form elements

As described, Form Builder automatically generates form elements based on the model attributes. However, you can customize the form structure by using only method.

private function form(): EloquentForm
{
    return EloquentForm::make(Customer::class)
        ->only('name', 'email');
}

# Ordering form elements

You can control the order of form elements by using the order method.

private function form(): EloquentForm
{
    return EloquentForm::make(Customer::class)
        ->order('email', 'name');
}

# Customizing form elements

You can customize form elements by using the map method. This method allows you to modify the form element instance before it is rendered.

use Mattbit\Zinq\Form\ElementContract;

private function form(): EloquentForm
{
    return EloquentForm::make(Customer::class)
        ->map('email', function (ElementContract $element) {
            return $element->label('Email address')->placeholder('Enter your email');
        });
}

# Reusable Eloquent forms

If you want to create a form that can be reused across multiple components, we recommend creating a dedicated Eloquent Form class. This approach ensures consistency, maintainability, and easy reuse throughout your application.

namespace App\Forms;

use App\Models\Customer;
use Mattbit\Zinq\Form\AbstractEloquentForm;

class CustomerForm extends AbstractEloquentForm
{
    protected function eloquentModel(): string
    {
        return Customer::class;
    }
    
    public function rules(): array
    {
        return [
            'name' => 'required',
            'email' => 'required|email',
        ];
    }
    
    protected function configure(): void
    {
        // Use this method to customize the form structure.
        
        $this
            ->only('name', 'email')
            ->order('email', 'name')
            ->map('email', function (ElementContract $element) {
                return $element->label('Email address')->placeholder('Enter your email');
            });
    }
}

# Using the reusable form

Now you can simply inject the CustomerForm into your Livewire component and render it in the view.

use App\Forms\CustomerForm;
use Livewire\Component;

class CreateCustomer extends Component
{
    public array $data = [];

    public function save(CustomerForm $form): void
    {
        $validated = $form->validate($this->data);
        
        // Save the validated data to the database
    }

    public function render(CustomerForm $form): string
    {
        return view('livewire.create-customer', ['form' => $form]);
    }
}