Filament Timeline View Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require devletes/filament-timeline-view
   php artisan filament:assets
   

2. First Use Case: Add TimelineEntry to a Filament table column in a resource's table() method:

   use Devletes\FilamentTimelineView\Tables\Columns\TimelineEntry;
   
   public function table(Table $table): Table
   {
       return $table
           ->columns([
               TimelineEntry::make()
                   ->title('title')
                   ->content('body')
                   ->time('published_at'),
           ])
           ->asTimeline();
   }
   

Where to Look First

• README.md: Focus on the "Usage" section for quick examples.
• Source Code: Explore src/Tables/Columns/TimelineEntry.php for customization options.
• Blade Templates: Check resources/views/vendor/filament-timeline-view/ for styling hooks.

Implementation Patterns

Core Workflow

1. Data Preparation: Ensure your query returns data with the fields specified in TimelineEntry (e.g., title, content, time). Use closures for dynamic data:

   TimelineEntry::make()
       ->title(fn ($record) => $record->formattedTitle())
       ->content('description')
   

2. Grouping: Use Filament’s Group for date-based grouping:

   ->defaultGroup(Group::make('published_at')->date()->orderQueryUsing(fn ($query) => $query->orderByDesc('published_at')))
   

3. Actions: Attach actions via recordActions:

   ->recordActions([
       EditAction::make(),
       DeleteAction::make(),
   ])
   

4. Pagination: Replace pagination with "Load More":

   ->paginated([5]) // Loads 5 records initially, then 5 more per click
   

Integration Tips

• Widgets: Use TableWidget for dashboard timelines:

  class TimelineWidget extends TableWidget {
      public function table(Table $table): Table {
          return $table
              ->columns([TimelineEntry::make()->title('title')->content('body')])
              ->asTimeline();
      }
  }
  

• Custom Layouts: Replace TimelineEntry with Stack/Split for full control:

  ->columns([
      Stack::make([
          TextColumn::make('title'),
          TextColumn::make('content'),
      ]),
  ])
  

• Dark Mode: Leverage Filament’s built-in dark mode support—no extra config needed.

Gotchas and Tips

Pitfalls

1. Date Grouping Order: Filament’s default Group sorts ascending (oldest first). Override with:

   ->orderQueryUsing(fn ($query) => $query->orderByDesc('published_at'))
   

2. Pagination Conflicts: Avoid mixing paginated([5, 10]) with asTimeline(). Only the first value (5) is used for "Load More."

3. Collapsible Groups: Collapsible groups require ->collapsible() on the Group, but only works with date groups.

4. CSS Overrides: Custom properties (e.g., --ftv-line-color) must target .ftv-shell or .ftv-group-body. Use:

   .fi-ta-timeline .ftv-shell {
       --ftv-line-color: #ff0000;
   }
   

Debugging

• Missing Styles: Run php artisan filament:assets if CSS isn’t loading.
• Blank Cards: Verify TimelineEntry fields match your model’s attributes or closures.
• Actions Not Showing: Ensure recordActions contains at least one ActionGroup.

Extension Points

1. Custom Templates: Override Blade templates in resources/views/vendor/filament-timeline-view/ (e.g., timeline-entry.blade.php).

2. Dynamic Data: Use closures for dynamic content:

   ->image(fn ($record) => $record->getCoverUrl())
   

3. Theming: Extend CSS variables for global theming:

   .dark .ftv-shell {
       --ftv-card-surface: #333;
   }
   

4. Localization: Translate date headers (e.g., "Today") via Filament’s filament.php language files:

   'collapsed_summary' => '{{ $count }} posts hidden',