Livewire Datatables Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mediconesystems/livewire-datatables
   

   For Laravel 9, also run:

   composer require psr/simple-cache:^1.0 maatwebsite/excel
   

2. Publish Config (Optional):

   php artisan vendor:publish --provider="MedicOneSystems\LivewireDatatable\LivewireDatatableServiceProvider"
   

3. First Usage: Create a Livewire component:

   php artisan make:livewire Admin/UserDatatable
   

   Update the component:

   <?php
   
   namespace App\Http\Livewire\Admin;
   
   use MedicOneSystems\LivewireDatatable\Columns\Column;
   use MedicOneSystems\LivewireDatatable\Http\LivewireDatatable;
   use App\Models\User;
   
   class UserDatatable extends LivewireDatatable
   {
       public function configure(): void
       {
           $this->setPrimaryKey('id');
           $this->setModel(User::class);
           $this->setSearch(['name', 'email']);
           $this->setPerPage(10);
       }
   
       public function columns(): array
       {
           return [
               Column::make("ID", "id"),
               Column::make("Name", "name"),
               Column::make("Email", "email"),
           ];
       }
   }
   

4. Render in Blade:

   <livewire:admin.user-datatable />
   

First Use Case: Basic CRUD Table

• Scenario: Display a list of users with pagination, search, and sorting.
• Steps:
  1. Use the configure() method to set the model, primary key, and searchable fields.
  2. Define columns in the columns() method.
  3. Add the Livewire component to your Blade view.

Implementation Patterns

Core Workflows

1. Data Binding

• Model Binding:

  public function configure(): void
  {
      $this->setModel(User::class);
  }
  

• Query Builder Binding:

  public function configure(): void
  {
      $this->setQuery(\DB::table('users'));
  }
  

2. Column Customization

• Basic Column:

  Column::make("Name", "name")
  

• Formatted Column:

  Column::make("Full Name", "name")
      ->format(fn($value, $row) => ucfirst($value))
  

• Computed Column:

  Column::make("User Role", "role")
      ->format(fn($value) => $value === 'admin' ? 'Administrator' : 'User')
  

3. Filtering

• Simple Filter:

  public function configure(): void
  {
      $this->addFilter(
          Column::make("Active Users", "active")
              ->boolean()
      );
  }
  

• Date Filter:

  $this->addFilter(
      Column::make("Created At", "created_at")
          ->date()
  );
  

• Select Filter:

  $this->addFilter(
      Column::make("Status", "status")
          ->select([
              '' => 'All',
              'active' => 'Active',
              'inactive' => 'Inactive'
          ])
  );
  

4. Complex Query Builder

• Combined Filters:

  public function configure(): void
  {
      $this->setQuery($this->query()->when(
          $this->getFilter('active'),
          fn($query) => $query->where('active', $this->getFilter('active'))
      ));
  }
  

5. Mass Actions

• Bulk Actions:

  public function configure(): void
  {
      $this->addAction(
          Action::make('Delete')
              ->icon('trash')
              ->color('danger')
              ->action(fn($row) => $this->deleteUser($row))
      );
  }
  

6. Column Groups

• Grouping Columns:

  public function columns(): array
  {
      return [
          ColumnGroup::make([
              Column::make("ID", "id"),
              Column::make("Name", "name"),
          ], "User Info"),
      ];
  }
  

Integration Tips

Livewire Events

• Custom Events:

  public function mount(): void
  {
      $this->dispatchBrowserEvent('user-updated');
  }
  

Tailwind Styling

• Custom CSS Classes:

  public function configure(): void
  {
      $this->setTableClasses('bg-white');
  }
  

Alpine.js Integration

• Dynamic Actions:

  <script>
      document.addEventListener('livewire:init', () => {
          Alpine.data('tableActions', () => ({
              confirmDelete(id) {
                  if (confirm('Are you sure?')) {
                      @this.call('deleteUser', id);
                  }
              }
          }));
      });
  </script>
  

Gotchas and Tips

Pitfalls

1. Model vs Query Builder

• Issue: Forgetting to set the model or query builder can result in undefined behavior.
• Fix: Always define either setModel() or setQuery() in configure().

2. Column Naming Conflicts

• Issue: Using reserved keywords (e.g., order, limit) as column names can cause SQL errors.
• Fix: Use aliases in your query or rename columns in the columns() method.

3. Pagination Issues

• Issue: Pagination not working due to incorrect setPerPage() or missing setPrimaryKey().
• Fix: Ensure setPrimaryKey() is set and setPerPage() is configured.

4. Filter Not Applying

• Issue: Filters not updating the query due to incorrect filter configuration.
• Fix: Verify filter types (boolean, date, select) and ensure the configure() method updates the query correctly.

5. Mass Action Conflicts

• Issue: Mass actions not triggering due to incorrect row selection logic.
• Fix: Ensure the action method is properly bound to the Livewire component.

Debugging Tips

1. Log Queries

• Use:

  \DB::enableQueryLog();
  $this->query()->get();
  \Log::info(\DB::getQueryLog());
  

2. Check Livewire State

• Use:

  dd($this->getFilter('column_name'));
  

3. Tailwind Conflicts

• Use: Inspect the rendered HTML to ensure Tailwind classes are correctly applied.

Extension Points

1. Custom Columns

• Extend: Create a custom column class by extending MedicOneSystems\LivewireDatatable\Columns\Column.

2. Custom Actions

• Extend: Create custom actions by extending MedicOneSystems\LivewireDatatable\Actions\Action.

3. Custom Filters

• Extend: Implement custom filter logic by overriding the configure() method and adding custom filter logic.

4. Custom Styling

• Extend: Override the default Tailwind styles by publishing the config and customizing the CSS.

5. Custom Query Logic

• Extend: Override the buildQuery() method to inject custom query logic.

Configuration Quirks

1. Published Config

• Location: config/livewire-datatables.php
• Key Points:
  • table_classes: Customize the table container classes.
  • thead_classes: Customize the header classes.
  • tbody_classes: Customize the body classes.

2. Alpine.js Dependencies

• Ensure: Alpine.js is included in your layout file before the Livewire component.

3. Livewire Version Compatibility

• Check: Ensure compatibility with your Livewire version (tested with Livewire 2.x).

4. Tailwind Version

• Check: Ensure Tailwind CSS is properly configured in your project.

Performance Tips

1. Eager Loading

• Use:

  public function configure(): void
  {
      $this->setModel(User::class)->setRelation('role', 'role');
  }
  

2. Select Specific Columns

• Use:

  public function configure(): void
  {
      $this->setQuery(User::select('id', 'name', 'email'));
  }
  

3. Lazy Loading

• Use: Implement lazy loading for large datasets by using cursor() instead of get().

4. Caching

• Use: Cache frequent queries using Laravel's cache system.

Example: Advanced Implementation

<?php

namespace App\Http\Livewire\Admin;

use MedicOneSystems\LivewireDatatable\Columns\Column;
use MedicOneSystems\