README

A Laravel package that adds dynamic data tables to Eloquent models with filtering, sorting, and customizable action buttons. Built with Bootstrap 5 and htmx for seamless, modern web applications.

What This Package Does

This package transforms your Eloquent models into powerful, interactive data tables with:

• Dynamic Data Tables - Automatically generate tables from your models
• Advanced Filtering - Search and filter data with multiple criteria
• Sorting Capabilities - Sort by any column with ascending/descending options
• Customizable Actions - Add custom action buttons for each row
• Real-time Updates - htmx-powered interactions without page reloads
• Bootstrap 5 Styling - Modern, responsive UI components

All tables are fully responsive and provide a seamless user experience with instant filtering and sorting.

Requirements

Frontend Dependencies

This package assumes you have the following assets available in your project:

• Bootstrap 5 - for styling the generated tables and UI components
• htmx - for handling AJAX requests and seamless interactions

Installation

1. Install the package:

   composer require andreazorzi/search-table

2. Install frontend dependencies (if not already installed):

   npm install bootstrap@5 htmx.org

Setup

Controller Configuration

Add the SearchController trait to any model controller you need to be searchable:

<?php

namespace App\Http\Controllers;

use SearchTable\Traits\SearchController;

class UserController extends Controller
{
    use SearchController;
    
    // Your existing controller methods...
}

Model Configuration

Add the SearchModel trait and configure the $table_fields variable in your model:

<?php

namespace App\Models;

use SearchTable\Traits\SearchModel;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use SearchModel;
    
    // Mandatory: Define which fields to display and their behavior
    protected static $table_fields = [
        "username" => [
            "filter" => true,
            "sort" => "asc"
        ],
        "name" => [
            "filter" => true,
        ],
        "email" => [
            "filter" => true,
        ]
    ];
    
    // Optional: Define custom actions for each row
    public function getTableActions($model_name, $key): array
    {
        return [
            [
                "attributes" => 'data-id="'.$key.'" hx-get="'.route($model_name.".show", [$key ?? 0]).'" hx-target="#modal .modal-content"',
                "content" => '<i class="table-search-preview fa-solid fa-pen"></i>'
            ]
        ];
    }
}

Usage

Basic Implementation

Include the SearchTable component in your Blade views:

<x-search-table::table :model="new App\Models\User()"/>

Component Parameters

Example with Parameters

Configuration

Table Fields Configuration

The $table_fields array defines how each model attribute should be displayed and behave in the table:

Basic Parameters

Customization Parameters

Custom filters attribute example

// Merged attributes
"custom-filter" => "CONCAT(first_name, ' ', last_name)"

// Manipulated data
"custom-filter" => "CASE WHEN status = 0 THEN 'New' WHEN status = 1 THEN 'In Progress' ELSE 'Finished' END"

// Model relationship
"custom-filter" => "(SELECT d.name FROM departments d WHERE d.id = department_id)"

// Model multiple relationship (Advanced Type: in-array)
"custom-filter" => "(SELECT GROUP_CONCAT(t.name SEPARATOR ', ') FROM tags t join user_tag ut on ut.tag_id = t.id WHERE ut.user_username = users.username)"

Advanced Filter Types

Example: Complete Field Configuration

protected static $table_fields = [
    "id" => [
        "sort" => "desc",
        "hidden" => true
    ],
    "full_name" => [
        "filter" => true,
        "custom-label" => "Full Name",
        "custom-value" => "getFullName",
        "custom-filter" => "CONCAT(first_name, ' ', last_name)"
    ],
    "email" => [
        "filter" => true,
    ],
    "created_at" => [
        "filter" => true,
        "advanced-type" => "date-range",
        "custom-label" => "Registration Date"
    ],
    "department" => [
        "filter" => true,
        "custom-value" => "getDepartmentName",
        "custom-filter" => "(SELECT d.name FROM departments d WHERE d.id = department_id)"
    ],
    "enabled" => [
        "filter" => true,
        "custom-label" => "Status"
        "custom-value" => "getStatus",
    ]
];

// Custom value methods
public function getFullName(){
    return $this->first_name . ' ' . $this->last_name;
}

public function getDepartmentName(){
    return $this->department->name;
}

public function getStatus(){
    return $this->enabled ? "Enabled" : "Disabled";
}

Advanced Features

Advanced Filters

Create custom advanced filters by adding a Blade file at: resources/views/components/search-table-filters/[model-name]-filters.blade.php

The example below use Selectize for manage the multiple select.

@use(App\Models\User)

<div class="col-md-4">
    <label>Status</label>
    <select class="selectize" multiple name="advanced_search[enabled][]">
        @foreach (["Disabled", "Enabled"] as $key => $value)
            <option value="{{$key}}">{{$value}}</option>
        @endforeach
    </select>
</div>

<div class="col-md-4">
    <label>Type</label>
    <select class="selectize" multiple name="advanced_search[type][]">
        @foreach (User::groupBy("type")->pluck("type")->toArray() as $type)
            <option>{{$type}}</option>
        @endforeach
    </select>
</div>

<!-- Many-to-many relationship filter with operators -->
<div class="col-md-4">
    <label>Groups</label>
    <div class="input-group">
        <span class="input-group-text">
            <select class="advance-filter form-control p-0 border-0 bg-transparent" name="advanced_search[filter_operators][groups]">
                <option value="AND">AND</option>
                <option value="OR">OR</option>
            </select>
        </span>
        <select class="selectize" multiple name="advanced_search[groups][]">
            @foreach (Group::get() as $group)
                <option value="{{$group->id}}">{{$group->name}}</option>
            @endforeach
        </select>
    </div>
</div>

<script>
    document.addEventListener("DOMContentLoaded", function() {
        $(".selectize").selectize({
            plugins: ["remove_button"],
            onChange: function(value) {
                $("#page").val(1);
                htmx.trigger("#page", "change");
            },
            onDropdownOpen: function() {
                for (const select of $(".selectize.selectized")) {
                    if(select !== this.$input[0]){
                        select.selectize.close();
                    }
                }
            }
        });
    });
</script>

Custom Action Buttons

Define custom actions for each table row:

public function getTableActions($model_name, $key): array{
    return [
        [
            "attributes" => 'hx-get="'.route($model_name.".edit", $key).'" hx-target="#modal .modal-content"',
            "content" => '<i class="fa-solid fa-pen"></i> Edit'
        ],
        [
            "attributes" => 'hx-delete="'.route($model_name.".destroy", $key).'" hx-confirm="Are you sure?"',
            "content" => '<i class="fa-solid fa-trash text-danger"></i> Delete'
        ]
    ];
}

Excample

Simple User Table

// Model
protected static $table_fields = [
    "name" => ["filter" => true, "sort" => "asc"],
    "email" => ["filter" => true],
    "created_at" => ["custom-label" => "Joined"]
];

// Blade
<x-search-table::table :model="new App\Models\User()"/>

Advanced Product Table with Relationships

// Model
protected static $table_fields = [
    "name" => ["filter" => true, "sort" => "asc"],
    "category" => [
        "filter" => true,
        "custom-value" => "getCategoryName",
        "custom-filter" => "(SELECT c.name FROM categories c WHERE c.id = category_id)"
    ],
    "price" => ["sort" => "desc"],
    "tags" => [
        "filter" => true,
        "custom-value" => "getTagsText",
        "advanced-type" => "in-array"
    ]
];

// Blade with advanced filters
<x-search-table::table 
    :model="new App\Models\Product()" 
    :showadvancefilters="true"
    :disableaddbutton="false"
/>

The MIT License (MIT)

Copyright © 2025 Andrea Zorzi info@zorziandrea.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.