Filament Timeline View Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require devletes/filament-timeline-view
   

   No additional configuration or service provider registration is required.

2. Basic Usage: Add the asTimeline() macro to any Filament Table query builder:

   use Devletes\FilamentTimelineView\TableMacros;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               TimelineEntry::make('title', 'Title'),
               // Other columns...
           ])
           ->asTimeline();
   }
   

3. First Use Case: Convert a standard Filament table (e.g., Post records) into a chronological timeline with minimal effort. The package automatically groups entries by date, adds avatars (if avatar column exists), timestamps, and collapsible day headers.

Implementation Patterns

Core Workflows

1. Timeline Conversion:

   • Replace ->paginate() with ->asTimeline() to transform a table into a scrollable, date-grouped feed.
   • Example:

     $table->query(
         Post::query()
             ->orderBy('created_at', 'desc')
             ->asTimeline()
     );
     

2. Double-Sided Timeline: Use ->asDoubleSidedTimeline() for bidirectional timelines (e.g., project milestones with past/future separation):

   $table->query(
       Project::query()
           ->orderBy('due_date')
           ->asDoubleSidedTimeline()
   );
   

3. Customizing Timeline Entries: Extend the TimelineEntry column to add custom fields or styling:

   TimelineEntry::make('content', 'Content')
       ->avatarColumn('user_avatar') // Override default avatar column
       ->dateColumn('published_at')  // Override default date column
       ->badge('status')            // Add a status badge
       ->icon('heroicon-o-pencil')  // Custom icon
       ->collapsible()              // Enable collapsible groups
       ->loadMoreButton();           // Show "Load More" button
   

4. Integration with Filament Actions: Leverage Filament’s built-in actions (e.g., EditAction, DeleteAction) directly in the timeline:

   $table->actions([
       EditAction::make(),
       DeleteAction::make(),
   ]);
   

5. Dynamic Grouping: Group entries by custom logic (e.g., week/month) via the groupBy method:

   $table->query(
       Event::query()
           ->asTimeline()
           ->groupBy(fn ($query) => $query->selectRaw('DATE_FORMAT(created_at, "%Y-%m")'))
   );
   

6. Embedding in Filament Panels: Use the timeline in any Filament resource/page:

   public static function table(Table $table): Table
   {
       return $table
           ->columns([...])
           ->asTimeline();
   }
   

Gotchas and Tips

Common Pitfalls

1. Missing Date Column: The package defaults to created_at. Ensure your model has a datetime column or explicitly set it:

   TimelineEntry::make('title')
       ->dateColumn('custom_date_column');
   

2. Pagination Conflicts: Avoid mixing ->paginate() with ->asTimeline(). The macro handles pagination internally.

3. Avatar Column Mismatch: If using avatarColumn(), ensure the referenced column exists and returns a URL or Filament-compatible avatar data.

4. Performance with Large Datasets: Timeline views load entries in batches. For >1000 records, optimize with:

   ->asTimeline()
       ->loadMoreBatchSize(50)
       ->initialLoadBatchSize(20);
   

Debugging Tips

1. Check Registered Macros: Verify the macro is registered in your table:

   dd($table->getMacros()); // Should include 'asTimeline'
   

2. Inspect Query: Log the generated query to debug grouping/filters:

   ->asTimeline()
       ->queryLog(); // Add this to see the SQL
   

3. Override Default Styling: Customize the timeline’s CSS via Filament’s styles method or global CSS:

   $table->styles([
       'timeline' => 'gap-4',
       'entry' => 'border rounded-lg',
   ]);
   

Extension Points

1. Custom Timeline Layout: Override the default Blade view by publishing and modifying:

   php artisan vendor:publish --tag=filament-timeline-view-views
   

   Edit resources/views/vendor/filament-timeline-view/timeline.blade.php.

2. Add Custom Entry Components: Extend the TimelineEntry class to support new features (e.g., attachments, comments):

   class CustomTimelineEntry extends TimelineEntry
   {
       public static function make(string $column, ?string $name = null): static
       {
           return parent::make($column, $name)
               ->extraAttribute('custom_field', fn ($record) => $record->custom_field);
       }
   }
   

3. Localization: Translate labels (e.g., "Load More") by publishing the language file:

   php artisan vendor:publish --tag=filament-timeline-view-lang
   

   Override in resources/lang/{locale}/filament-timeline-view.php.

4. Server-Side Processing: For complex timelines, use Filament’s serverSide() with asTimeline():

   $table->query(
       Post::query()
           ->serverSide()
           ->asTimeline()
   );
   

5. Dark Mode Support: Ensure your timeline entries respect Filament’s dark mode by using Filament’s built-in classes (e.g., dark:bg-gray-800).