Livewire Datatable Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require developerawam/livewire-datatable
   

   Publish config (optional):

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

2. First Use Case:

   use Developerawam\LivewireDatatable\LivewireDatatable;
   use App\Models\User;
   
   class UserTable extends LivewireDatatable
   {
       public $model = User::class;
   }
   

   Blade template:

   <livewire:user-table />
   

Where to Look First

• Config File: config/livewire-datatable.php (for global defaults)
• Documentation: Focus on the Basic Usage section in the README
• Example Components: Check the resources/views/vendor/livewire-datatable directory for default templates

Implementation Patterns

Core Workflow

1. Define the Table Class: Extend LivewireDatatable and specify your model:

   class PostTable extends LivewireDatatable
   {
       public $model = Post::class;
   
       // Optional: Override defaults
       public $perPage = 20;
   }
   

2. Customize Columns:

   public function columns()
   {
       return [
           'id' => 'ID',
           'title' => 'Title',
           'published_at' => (new CarbonColumn('published_at'))
               ->format('Y-m-d'),
       ];
   }
   

3. Add Filters:

   public function filters()
   {
       return [
           'published' => [
               'type' => 'boolean',
               'label' => 'Published',
           ],
           'category' => [
               'type' => 'select',
               'label' => 'Category',
               'options' => Category::pluck('name', 'id'),
           ],
       ];
   }
   

4. Integrate with Views:

   <livewire:post-table
       :columns="$columns"
       :filters="$filters"
   />
   

Common Patterns

• Reusable Components: Create base table classes for shared functionality (e.g., BaseAdminTable).
• Dynamic Columns: Use column() method to conditionally include columns:

  public function columns()
  {
      $columns = ['id', 'name'];
      if (auth()->can('view-extra')) {
          $columns[] = 'metadata';
      }
      return $columns;
  }
  

• API Integration: Use the getQuery() method to fetch data for external APIs:

  public function getQuery()
  {
      return $this->model::query()
          ->where('active', true);
  }
  

Integration Tips

• Form Integration: Combine with Livewire forms for inline editing:

  <livewire:post-table :wire:key="$this->editMode">
      @include('tables.edit-modal')
  </livewire:datatable>
  

• Event Handling: Listen to table events (e.g., datatable-updated):

  protected $listeners = ['datatable-updated' => 'syncFilters'];
  

• Testing: Use Livewire::test() with assertSeeInTable() helper methods.

Gotchas and Tips

Common Pitfalls

1. Query Performance:

   • Issue: Slow queries on large datasets.
   • Fix: Use select() in getQuery() to limit columns:

     public function getQuery()
     {
         return $this->model::query()->select('id', 'name', 'email');
     }
     

   • Tip: Add database indexes for filtered/sorted columns.

2. Relationship Loading:

   • Issue: N+1 queries when eager-loading relationships.
   • Fix: Use with() in getQuery():

     public function getQuery()
     {
         return $this->model::with('author')->query();
     }
     

   • Tip: For complex relationships, use loadMissing() or constrain().

3. Configuration Overrides:

   • Issue: Per-component settings not applying.
   • Fix: Ensure public $perPage = ... is defined before columns()/filters():

     public $perPage = 50; // Must come first
     

4. Caching Headers:

   • Issue: Stale data in browser.
   • Fix: Add wire:key dynamically or use wire:ignore for static parts.

Debugging Tips

• Log Queries: Enable query logging in config/livewire-datatable.php:

  'debug' => [
      'query_logging' => true,
  ],
  

• Check Wire Events: Use dd($this->emit('alert', 'Debug info')) to inspect state.
• Inspect Requests: Temporarily add dd($this->request) in mount() to see incoming data.

Extension Points

1. Custom Columns:

   • Extend Developerawam\LivewireDatatable\Column for reusable column types:

     class StatusColumn extends Column
     {
         public function render($value)
         {
             return view('tables.status-badge', ['status' => $value]);
         }
     }
     

2. Custom Actions:

   • Add buttons via the actions() method:

     public function actions()
     {
         return [
             'edit' => 'Edit',
             'delete' => 'Delete',
         ];
     }
     

   • Handle actions in handleAction():

     public function handleAction($action, $id)
     {
         if ($action === 'delete') {
             $this->model::find($id)->delete();
         }
     }
     

3. Bulk Actions:

   • Use bulkActions() for multi-row operations:

     public function bulkActions()
     {
         return [
             'export' => 'Export Selected',
             'delete' => 'Delete Selected',
         ];
     }
     

   • Implement logic in handleBulkAction():

     public function handleBulkAction($action, $ids)
     {
         if ($action === 'delete') {
             $this->model::whereIn('id', $ids)->delete();
         }
     }
     

4. Custom Templates:

   • Override default views by publishing assets:

     php artisan vendor:publish --tag=livewire-datatable-views
     

   • Modify resources/views/vendor/livewire-datatable/table.blade.php.

Pro Tips

• Lazy Loading: Use lazy property to defer table initialization:

  <livewire:post-table :lazy="true" />
  

• Conditional Logic: Dynamically adjust table behavior:

  public function mount()
  {
      $this->perPage = auth()->user()->isAdmin() ? 100 : 20;
  }
  

• Localization: Override labels in config:

  'labels' => [
      'search' => __('Search'),
      'per_page' => __('Items per page'),
  ],
  

• Access Control: Restrict table access:

  public function mount()
  {
      $this->authorize('view', $this->model);
  }