Filament Calendar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require theabhishekin/filament-calendar
   

   Publish the config (if needed):

   php artisan vendor:publish --tag=filament-calendar-config
   

2. Basic Usage Register the widget in a Filament page/resource:

   use TheAbhishekIN\FilamentCalendar\Widgets\Calendar;
   
   public static function getWidgets(): array
   {
       return [
           Calendar::make()
               ->query(fn () => YourEventModel::query())
               ->eventUrl(fn ($record) => route('events.show', $record))
               ->dateClick(fn ($date) => YourEventModal::make($date)),
       ];
   }
   

3. First Use Case Display a month-view calendar for appointments with a "Create Appointment" modal:

   Calendar::make()
       ->query(Appointment::query())
       ->eventUrl(fn ($record) => route('appointments.show', $record))
       ->dateClick(fn ($date) => AppointmentModal::make($date))
       ->views(['dayGridMonth', 'timeGridWeek'])
   

Implementation Patterns

Core Workflows

1. Data Integration

   • Query Binding: Use query() to bind an Eloquent query builder. Example:

     ->query(fn () => Event::where('is_published', true)->orderBy('starts_at'))
     

   • Event Formatting: Customize event display with eventFormatter():

     ->eventFormatter(fn ($event) => [
         'title' => $event->title,
         'start' => $event->starts_at->format('Y-m-d\TH:i:s'),
         'end' => $event->ends_at->format('Y-m-d\TH:i:s'),
         'color' => $event->color_hex,
         'url' => route('events.show', $event),
     ])
     

2. Modal Integration

   • Date Click: Trigger a modal or redirect on day click:

     ->dateClick(fn ($date) => EventModal::make($date))
     

   • Event Click: Redirect or open modal:

     ->eventClick(fn ($event) => redirect($event->url))
     

3. Filtering

   • Default Filters: Use built-in filters (e.g., staff, status):

     ->filters(['staff', 'status'])
     

   • Custom Filters: Override filtersForm() in a custom widget class:

     public function filtersForm(): array
     {
         return [
             Select::make('event_type')
                 ->options(EventType::all()->pluck('name', 'id')),
         ];
     }
     

4. View Customization

   • Available Views: dayGridMonth, timeGridWeek, timeGridDay, listWeek.
   • Default View: Set via defaultView():

     ->defaultView('timeGridWeek')
     

   • View Toggle: Enable/disable views:

     ->views(['dayGridMonth', 'timeGridWeek'])
     

5. Styling

   • Dark Mode: Automatically adapts to Filament’s dark mode.
   • Custom Colors: Use color() to set default event colors:

     ->color('#3b82f6') // Default blue
     

Advanced Patterns

1. Dynamic Data Loading

   • Use livewire:model to update events in real-time:

     public function updatedSearch($search)
     {
         $this->query()->where('title', 'like', "%{$search}%");
     }
     

2. Event Actions

   • Attach Filament Actions to events:

     ->eventActions([
         Action::make('edit')
             ->url(fn ($record) => route('events.edit', $record)),
         Action::make('delete')
             ->requiresConfirmation()
             ->action(fn ($record) => $record->delete()),
     ])
     

3. External Integration

   • Sync with Google Calendar or other APIs via eventFormatter:

     ->eventFormatter(fn ($event) => [
         'start' => $event->google_event->start->format('Y-m-d\TH:i:s'),
         // ...
     ])
     

Gotchas and Tips

Common Pitfalls

1. Date Formatting

   • Ensure starts_at/ends_at are Carbon instances or ISO strings (Y-m-d\TH:i:s). Non-compliant formats may break event rendering.
   • Fix: Use ->format('Y-m-d\TH:i:s') in eventFormatter.

2. Modal Persistence

   • If using dateClick or eventClick with modals, ensure the modal’s Livewire component is properly scoped to avoid duplicate instances.
   • Tip: Use ->mountUsing(fn () => new YourModal()) in the modal class.

3. Filter Query Binding

   • Filters are applied via JavaScript, but the initial query must account for them. Use updatedFilters() in your Livewire component:

     public function updatedFilters(array $filters)
     {
         $query = Event::query();
         if (isset($filters['staff'])) {
             $query->where('staff_id', $filters['staff']);
         }
         $this->query = $query;
     }
     

4. Event Overlap Handling

   • FullCalendar handles overlaps by default, but custom eventFormatter may break this. Ensure start/end are properly formatted.

5. Dark Mode Conflicts

   • If dark mode styling is inconsistent, override the widget’s CSS:

     ->extraAttributes(['class' => 'dark:bg-gray-800'])
     

Debugging Tips

1. Console Logs

   • Enable FullCalendar’s debug mode via config:

     'calendar' => [
         'debug' => env('FILAMENT_CALENDAR_DEBUG', false),
     ],
     

   • Check browser console for Alpine.js/FullCalendar errors.

2. Query Logging

   • Temporarily add ->toSql() to your query in eventFormatter to verify SQL:

     dd($this->query()->toSql());
     

3. Event Data Validation

   • Validate eventFormatter output matches FullCalendar’s expected structure:

     [
         'title' => string,
         'start' => string (ISO 8601),
         'end' => string (ISO 8601),
         'allDay' => bool (optional),
         'color' => string (hex, e.g., '#3b82f6'),
     ]
     

Extension Points

1. Custom Views

   • Extend the widget by creating a new class:

     class CustomCalendar extends Calendar
     {
         public function customizeView(): void
         {
             $this->extraAttributes(['data-custom' => 'true']);
         }
     }
     

2. Alpine.js Extensions

   • Add custom Alpine directives by publishing the package’s assets:

     php artisan vendor:publish --tag=filament-calendar-assets
     

   • Then extend in your layout:

     document.addEventListener('alpine:init', () => {
         Alpine.directive('custom-directive', (el, { expression }) => {
             // Logic here
         });
     });
     

3. Event Drop/Resize

   • Handle drag-and-drop events via eventDrop and eventResize:

     ->eventDrop(fn ($event) => $event->update(['ends_at' => $event->end]))
     ->eventResize(fn ($event) => $event->update(['ends_at' => $event->end]))
     

4. Localization

   • Override FullCalendar’s locale via config:

     'calendar' => [
         'locale' => 'es',
     ],
     

   • Requires FullCalendar’s locale bundle (e.g., fullcalendar-locale-es).