Livewire Datatable Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run composer require arkhas/livewire-datatable and publish optional config/views:

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

2. Generate a Datatable Component Use the Artisan command:

   php artisan make:datatable TasksTable
   

   This creates a scaffold with WithDatatable trait and basic setup.

3. Define Columns and Query In TasksTable.php, configure columns and query:

   public function setup(): void
   {
       $this->table = new EloquentTable(Task::query());
       $this->table->addColumn(new Column('id', 'ID'));
       $this->table->addColumn(new Column('title', 'Title'));
       $this->table->addColumn(new ActionColumn('actions', 'Actions'));
   }
   

4. Render the Component Add to a Blade view:

   <livewire:tasks-table />
   

First Use Case: Basic CRUD Table

• Use EloquentTable for Eloquent models.
• Add columns with addColumn() (e.g., Column, CheckboxColumn).
• Define actions (e.g., ActionColumn for edit/delete buttons).
• Example:

  $this->table->addColumn(new ActionColumn('actions', 'Actions'))
      ->addAction(new TableAction('Edit', 'edit', 'edit-task', 'primary'))
      ->addAction(new TableAction('Delete', 'delete', 'delete-task', 'danger'));
  

Implementation Patterns

Core Workflows

1. Data Binding

   • Use WithDatatable trait to auto-bind table data to Livewire properties.
   • Customize query logic in getQuery():

     public function getQuery()
     {
         return Task::query()->where('user_id', auth()->id());
     }
     

2. Column Customization

   • Basic Columns: Use Column for simple fields.
   • Checkbox Columns: Add bulk actions with CheckboxColumn.
   • Action Columns: Group actions (e.g., edit/delete) in ActionColumn or ColumnActionGroup.
   • Custom Rendering: Override render() in a column class:

     $this->table->addColumn(new Column('status', 'Status'))
         ->render(function ($value) {
             return $value === 'completed' ? '✅' : '⏳';
         });
     

3. Filtering

   • Simple Filters: Use Filter for text/number inputs.
   • Dropdown Filters: Use FilterOption for select boxes.
   • Date/Range Filters: Use DateFilter or RangeFilter.
   • Example:

     $this->table->addFilter(new Filter('title', 'Title'))
         ->addFilterOption(new FilterOption('status', 'Status', ['completed', 'pending']));
     

4. Exporting

   • Enable exports via config (config/livewire-datatable.php):

     'exports' => [
         'enabled' => true,
         'formats' => ['csv', 'excel', 'pdf'],
     ],
     

   • Add export button to the table:

     $this->table->addExportButton();
     

5. Pagination and Sorting

   • Auto-enabled via EloquentTable. Customize in getQuery():

     public function getQuery()
     {
         return Task::query()->orderBy($this->sortField, $this->sortDirection);
     }
     

Integration Tips

• Livewire Hooks: Use mount() for initialization logic:

  public function mount()
  {
      $this->table->setPerPage(10); // Default items per page
  }
  

• Dynamic Columns: Load columns dynamically based on user roles:

  if (auth()->user()->isAdmin()) {
      $this->table->addColumn(new Column('created_at', 'Created At'));
  }
  

• Reusable Components: Extract table logic into a base component for consistency:

  class BaseTable extends Component
  {
      use WithDatatable;
  
      public function setup()
      {
          $this->table->setPerPage(20);
          $this->table->addExportButton();
      }
  }
  

Gotchas and Tips

Pitfalls and Debugging

1. Query Overrides

   • Issue: Forgetting to chain getQuery() can break filtering/sorting.
   • Fix: Always return the query from getQuery():

     public function getQuery()
     {
         return Task::query()->where(...); // Return the query!
     }
     

2. Column Naming Conflicts

   • Issue: Column names clashing with Livewire properties (e.g., id).
   • Fix: Use unique aliases:

     $this->table->addColumn(new Column('id', 'ID', 'task_id'));
     

3. Filter Persistence

   • Issue: Filters not persisting across page reloads.
   • Fix: Ensure WithDatatable is used and filters are properly defined:

     $this->table->addFilter(new Filter('search', 'Search'))->debounce(500);
     

4. Performance with Large Datasets

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

       $this->table->getQuery()->select(['id', 'title', 'status']);
       

     • Add indexes to filtered/sorted columns in the database.

5. Flux Pro Dependency

   • Issue: Missing Flux Pro components (e.g., flux:alert).
   • Fix: Install Flux Pro or override views:

     composer require flux/flux-pro
     

Configuration Quirks

1. Default Per-Page Setting

   • Override in setup():

     $this->table->setPerPage(50);
     

   • Or via config:

     'default_per_page' => 25,
     

2. Export Formats

   • Requires spatie/laravel-data-export for CSV/Excel/PDF:

     composer require spatie/laravel-data-export
     

3. Custom Views

   • Publish views to override default templates:

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

   • Modify resources/views/vendor/livewire-datatable/....

Extension Points

1. Custom Columns

   • Extend Column class for complex rendering:

     class ProgressColumn extends Column
     {
         public function render($value)
         {
             return view('custom.progress', ['value' => $value]);
         }
     }
     

2. Custom Actions

   • Extend TableAction or ColumnAction for custom logic:

     class CustomAction extends TableAction
     {
         public function handle()
         {
             // Custom logic (e.g., API call)
         }
     }
     

3. Event Listeners

   • Listen for table events (e.g., row selection):

     $this->table->listen('rowSelected', function ($row) {
         $this->emit('rowSelected', $row);
     });
     

4. API Integration

   • Use getTableData() to fetch data via API:

     public function getTableData()
     {
         return Task::api()->get();
     }