Laravel Dashboard Calendar Tile Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-dashboard-calendar-tile
   

   Ensure laravel-dashboard is installed as a dependency.

2. Publish Config:

   php artisan vendor:publish --provider="Spatie\Dashboard\DashboardServiceProvider" --tag="dashboard-config"
   

   Locate the config/dashboard.php file and add the calendar tile to your dashboard configuration under tiles.

3. First Use Case:

   • Add the tile to your dashboard:

     use Spatie\Dashboard\Tiles\CalendarTile;
     
     return [
         'tiles' => [
             CalendarTile::class,
         ],
     ];
     

   • Configure Google Calendar API credentials in .env:

     GOOGLE_CALENDAR_CLIENT_ID=your_client_id
     GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret
     GOOGLE_CALENDAR_REDIRECT_URI=your_redirect_uri
     GOOGLE_CALENDAR_CALENDAR_ID=your_calendar_id
     

Implementation Patterns

Basic Workflow

1. Authentication:

   • Redirect users to Google OAuth for authentication:

     use Spatie\Dashboard\Tiles\CalendarTile;
     
     route('dashboard.calendar.auth', CalendarTile::class . '@authenticate');
     

   • Handle the callback in your routes:

     route('dashboard.calendar.callback', CalendarTile::class . '@handleCallback');
     

2. Displaying Events:

   • The tile automatically fetches events from the configured Google Calendar. Customize the view by extending the default blade template:

     @extends('dashboard::tiles.calendar-tile')
     @section('custom-script')
         // Add custom JS logic here
     @endsection
     

3. Integration with Dashboard:

   • Use the tile alongside other dashboard tiles:

     return [
         'tiles' => [
             CalendarTile::class,
             AnalyticsTile::class,
             StatsTile::class,
         ],
     ];
     

Advanced Patterns

• Dynamic Calendar Selection:

  • Pass a dynamic calendar ID via middleware or session:

    public function getCalendarId()
    {
        return session('selected_calendar_id') ?? config('dashboard.calendar_id');
    }
    

• Event Filtering:

  • Override the getEvents method in a custom tile class:

    use Spatie\Dashboard\Tiles\CalendarTile;
    
    class CustomCalendarTile extends CalendarTile
    {
        public function getEvents()
        {
            return parent::getEvents()->where('status', 'confirmed');
        }
    }
    

• Multi-Calendar Support:

  • Extend the tile to support multiple calendars:

    public function getCalendars()
    {
        return [
            ['id' => 'primary', 'name' => 'Work Calendar'],
            ['id' => 'personal', 'name' => 'Personal Calendar'],
        ];
    }
    

Gotchas and Tips

Common Pitfalls

1. Google API Credentials:

   • Ensure GOOGLE_CALENDAR_REDIRECT_URI matches the URI in your Google Cloud Console. Mismatches cause OAuth failures.
   • Use the Web Application type for OAuth credentials, not Installed App.

2. Caching Events:

   • The tile caches events by default. Clear the cache if events don’t update:

     php artisan cache:clear
     

   • Disable caching in config if real-time updates are critical:

     'cache_events' => false,
     

3. Timezone Issues:

   • Events may display incorrectly if the timezone isn’t set. Configure in .env:

     APP_TIMEZONE=America/New_York
     

4. Rate Limits:

   • Google Calendar API has quotas. Monitor usage in Google Cloud Console.

Debugging Tips

• OAuth Errors:

  • Check storage/logs/laravel.log for OAuth-related errors. Common issues include:
    • Missing scopes (https://www.googleapis.com/auth/calendar.readonly).
    • Invalid client_id or client_secret.

• Event Fetching:

  • Verify the GOOGLE_CALENDAR_CALENDAR_ID is correct. Use the Google Calendar API Explorer to test manually.

• Blade Template Overrides:

  • If customizations aren’t applying, ensure the template is published:

    php artisan vendor:publish --tag=dashboard-views
    

Extension Points

1. Custom Event Styling:

   • Override the getEventStyle method to customize event colors or labels:

     public function getEventStyle($event)
     {
         return ['background-color' => $event->status === 'confirmed' ? '#4CAF50' : '#FFEB3B'];
     }
     

2. Event Actions:

   • Add click handlers to events by extending the tile’s JavaScript:

     document.addEventListener('DOMContentLoaded', function() {
         document.querySelectorAll('.fc-event').forEach(event => {
             event.addEventListener('click', function() {
                 alert('Event clicked: ' + this.title);
             });
         });
     });
     

3. Localization:

   • Translate calendar labels by publishing the language files:

     php artisan vendor:publish --tag=laravel-dashboard-lang
     

   • Override in resources/lang/en/dashboard.php:

     'calendar' => [
         'title' => 'My Custom Calendar',
     ],
     

4. Testing:

   • Mock the Google API client in tests:

     $mockClient = Mockery::mock(\Google_Client::class);
     $mockClient->shouldReceive('getAccessToken')->andReturn(['access_token' => 'mock_token']);
     $this->app->instance(\Google_Client::class, $mockClient);