Table Builder

# Introduction

Zinq TableBuilder is a powerful tool designed to streamline the creation of tables from Eloquent Collections in Laravel and Livewire. With its intuitive API and minimal configuration, TableBuilder allows you to effortlessly display Eloquent models in a clean, responsive format. By leveraging <zinq:table> , it ensures your tables are fully responsive, accessible, and seamlessly adapt to both light and dark modes.

# Usage

To start using TableBuilder, you can use BuildsTables trait in your Livewire component:

use Mattbit\Zinq\Utilities\BuildsTables;

class Payments extends Component
{
    use BuildsTables;

    ...
}

Or you can simply inject TableBuilder instance:

use Mattbit\Zinq\Builders\TableBuilder;

class Payments extends Component
{
    public function render(TableBuilder $tableBuilder)
    {
        ...
    }
}

# Building

To build a table, you need to call tableFromCollection method from BuildsTable trait or fromCollection method on the builder instance. The method accepts an Eloquent Collection.

use Mattbit\Zinq\Utilities\BuildsTables;

class Payments extends Component
{
    use BuildsTables;

    public function render(): string
    {
        $table = $this->tableFromCollection(Payment::all());

        return view('livewire.payments', ['table' => $table]);
    }
}

# Displaying

Table can be used a string, so you can simply echo it in your blade template:

<div>
    {!! $table !!}
</div>

# Collection proxy

TableBuilder uses Illuminate\Support\Collection proxy to access collection methods. You can use all methods available in the Collection class.

<div>
    @if ($table->isEmpty())
        <p>No payments found.</p>
    @else
        <p>There are @{{ $table->count() }} payments.</p>
        {!! $table !!}
    @endif
</div>

# Customization

By default TableBuilder will display all columns from the model and will use the attribute name as a header.

# Hide

TableBuilder supports hidden attributes, which will not be displayed in the table.
If you wish to hide given attribute without modifying the model, you can use hide method.

public function render(): string
{
    return $this->tableFromCollection(Payment::all())
        ->hide('id', 'updated_at') // Hide id and updated_at attributes from the table
        ->render();
}

# Override

TableBuilder will use te Eloquent's getAttribute method to display the value of the attribute. If you wish to change this behaviour for specific attribute, you can use override method.

public function render(): string
{
    return $this->tableFromCollection(Payment::all())
        ->override('amount', function (Payment $payment) {
            // You can use $payment instance to display the value.
            return '$' . number_format($payment->amount, 2);
        })
        ->render();
}

# Rename

TableBuilder formats each attribute to prepare a nice label representation for you. It uppercase first letter, replaces any underscores with whitespaces and even formats id to be present as ID. If you want to display a custom header for given attribute, you can use rename method.

public function render(): string
{
    return $this->tableFromCollection(Payment::all())
        ->rename('created_at', 'Date')
        ->render();
}

# Add

Sometimes you need to display additional information in the table, like information from the related models. To fit this scenario, TableBuilder has add method to add a new column to the table.

public function render(): string
{
    return $this->tableFromCollection(Payment::with('user')->get())
        ->add('customer', fn (Payment $payment) => $payment->customer->name)
        ->rename('customer', 'Customer name') // You can rename the column as well
        ->render();
}

# Link

If you want to display a show button for each row, you can use link method. It will create a new column with a link to the given route.

public function render(): string
{
    return $this->tableFromCollection(Payment::with('user')->get())
        ->link(fn (Payment $payment) => route('payments.show', $payment->id))
        ->render();
}

# Date

TableBuilder will format date attributes using format specified in the config/zinq.php file. You can modify default date format by changing date_format key in the config file.

Or you can use override method to change the date format for specific attribute.

# Order

TableBuilder will display the columns in the order they are defined in the model. If you want to change the order of the columns, you can use order method.

public function render(): string
{
    return $this->tableFromCollection(Payment::all())
        ->order('customer', 'status', 'amount', 'created_at')
        ->render();
}

# Full example

Now we can combine all the methods to create a nice table.

public function render(): string
{
    return $this->tableFromCollection(Payment::with('user')->get())
        ->hide('id', 'updated_at')
        ->add('customer', fn (Payment $payment) => $payment->customer->name)
        ->override('amount', fn (Payment $payment) => '$' . number_format($payment->amount, 2))
        ->override('status', fn (Payment $payment) => match ($payment->status) {
            'processing' => '<zinq:badge sm info>Processing</zinq:badge>',
            'success' => '<zinq:badge sm success>Completed</zinq:badge>',
            'failed' => '<zinq:badge sm danger>Failed</zinq:badge>',
            default => '<zinq:badge sm>Unknown</zinq:badge>',
        })
        ->rename('created_at', 'Date')
        ->rename('customer', 'Customer name')
        ->link(fn (Payment $payment) => route('payments.show', $payment->id))
        ->order('customer', 'status', 'amount', 'created_at')
        ->render();
}

# Coming Soon

We’re constantly expanding the capabilities of Zinq, and some powerful TableBuilder new features are scheduled for release in early 2025:

• sorting
• filtering
• pagination

By purchasing a Zinq license today, you’ll secure lifetime access to all updates, ensuring you can take advantage of these features the moment they’re ready. Don’t miss this opportunity to lock in the promotional pricing now and guarantee your access to the best Zinq has to offer!