Tristen Tablesort Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/tristen-tablesort
   

   Add the package to your composer.json and run composer update.

2. Basic Usage Include the package in your Blade view:

   @use('ContaoComponents\Tristen\TableSort\TableSort')
   

   Initialize with a simple table:

   {{ TableSort::make('users', ['id', 'name', 'email']) }}
   

3. First Use Case Sort a Laravel Eloquent query result table:

   $users = User::all();
   return view('users.index', compact('users'))->with('sortableColumns', ['id', 'name', 'email']);
   

   In Blade:

   {{ TableSort::make('users', request('sort'), request('direction'), ['id', 'name', 'email']) }}
   

Implementation Patterns

Workflow Integration

1. Query Builder Integration Use middleware or a service to handle sorting logic:

   // app/Http/Middleware/HandleTableSort.php
   public function handle($request, Closure $next)
   {
       if ($request->has('sort')) {
           $query = User::query();
           $query->orderBy($request->sort, $request->direction ?? 'asc');
           $request->merge(['users' => $query->get()]);
       }
       return $next($request);
   }
   

2. Dynamic Column Handling Fetch sortable columns from a model or database:

   // app/Models/User.php
   public static function sortableColumns()
   {
       return ['id', 'name', 'email', 'created_at'];
   }
   

   Blade:

   {{ TableSort::make('users', request('sort'), request('direction'), User::sortableColumns()) }}
   

3. Pagination + Sorting Combine with Laravel's pagination:

   $users = User::orderBy(request('sort', 'id'), request('direction', 'asc'))
               ->paginate(10);
   

   Blade:

   {{ TableSort::make('users', request('sort'), request('direction'), ['id', 'name', 'email']) }}
   {{ $users->links() }}
   

4. Reusable Components Create a custom view component:

   // app/View/Components/SortableTable.php
   public function render()
   {
       return view('components.sortable-table', [
           'data' => $this->data,
           'columns' => $this->columns,
       ]);
   }
   

   Blade:

   <x-sortable-table :data="$users" :columns="['id', 'name', 'email']" />
   

Gotchas and Tips

Pitfalls

1. CSRF Conflicts Ensure your sort links include @csrf if using POST requests:

   {{ TableSort::make('users', ['csrf' => true]) }}
   

2. Case Sensitivity Default sorting may not handle case sensitivity. Use:

   $query->orderByRaw("UPPER($request->sort) $request->direction");
   

3. Reserved Words Avoid column names like order, desc, or asc to prevent SQL conflicts.

4. Default Sorting Override defaults in the constructor:

   {{ TableSort::make('users', 'name', 'desc', ['id', 'name', 'email']) }}
   

Debugging

• Check Request Data Dump request()->all() to verify sort/direction parameters are passed correctly.
• SQL Queries Use Laravel’s query logging:

  DEBUG_BAR_ENABLED=true
  

  Then check the debug bar for raw SQL.

Extension Points

1. Custom Sort Logic Extend the package via traits or decorators:

   // app/Services/CustomTableSort.php
   use ContaoComponents\Tristen\TableSort\TableSort as BaseTableSort;
   
   class CustomTableSort extends BaseTableSort
   {
       protected function getOrderBy($column)
       {
           if ($column === 'priority') {
               return "FIELD(priority, 1, 2, 3)";
           }
           return parent::getOrderBy($column);
       }
   }
   

2. Localization Override labels for sort directions:

   {{ TableSort::make('users')->setDirectionLabels([
       'asc' => __('Sort Ascending'),
       'desc' => __('Sort Descending'),
   ]) }}
   

3. Styling Customize icons/classes via config:

   // config/tablesort.php
   'icons' => [
       'asc' => 'fas fa-sort-up',
       'desc' => 'fas fa-sort-down',
   ],
   

   Then publish the config:

   php artisan vendor:publish --tag=tablesort-config