google_calendar_events

This module provides a suite of blocks to display upcoming events from a public Google Calendar. It uses the Google Calendar API v3 to fetch event data and offers flexible configuration options, caching, and theming capabilities.

FEATURES

• Multiple Blocks:
  • Upcoming Events: A configurable list of future events.
  • This Week's Events: Displays events for the current week, grouped by day.
  • Next Upcoming Event: Highlights the single next event with a live JavaScript countdown timer, perfect for "Next Service" or "Next Meeting" displays.
  • Google Calendar Embed: A simple block to embed the standard Google Calendar iframe.
• Flexible Display Options:
  • Group events by timeframe (Today, Tomorrow, This Week, Next 30 Days).
  • "Calendar Card" layout option for styling events as date cards.
  • Option to show events for "Today Only".
• Performance: Built-in caching for API responses to minimize API calls and improve page load times.
• API Key Management: Supports storing the Google API Key securely via the Key module or simple manual entry.
• Developer Friendly:
  • Fully themeable using Twig templates.
  • Extensive test coverage.

REQUIREMENTS

• Drupal 10, or 11
• PHP 8.1 or higher
• Google Cloud Platform project with the Google Calendar API enabled.
• A Public Google Calendar ID.

Optional Dependencies

• Key Module: Recommended for secure storage of the Google API Key.

INSTALLATION

Install as you would normally install a contributed Drupal module. Visit: https://www.drupal.org/node/1897420 for further information.

CONFIGURATION

1. Global Settings

Navigate to Configuration > Web services > Google Calendar Events (/admin/config/google_calendar_events/settings).

• API Key:
  • Manual: Paste your Google Calendar API key directly.
  • Key Module: Select an existing key from the Key module (ensure it is an 'Authentication' key type).
• Available Calendars: Add one or more Google Calendar IDs with friendly names. These will appear as options when configuring blocks.
  • Tip: To find your Calendar ID, go to your Google Calendar Settings > Integrate calendar > Calendar ID.
• Cache Duration: Set the duration (in seconds) to cache API responses. Default is 3600 seconds (1 hour).
• Date/Time Settings:
  • Date Format: Default PHP date format (e.g., l F j, Y).
  • Time Format: Default PHP time format (e.g., g:ia).

2. Block Placement

Navigate to Structure > Block layout and place one of the available blocks. You can also place the blocks using Layout Builder on your content items.

Upcoming Events Block

Displays a list of future events.

• Calendar: Select a calendar from your configured list.
• Number of Events: Max number of events to show.
• Show events from today only: Restrict the list to the current day.
• Display Settings:
  • Enable Day Grouping: Groups events into headers like "Today", "Tomorrow", "This Week", etc.
  • Event Display Type: Choose between 'Default List Layout' or 'Calendar Card Layout'.
• Custom Text: content to display when no events are found.
• "View all" Link: Configure a link to a full calendar page.

This Week's Events Block

Displays events for the current week (Sunday to Saturday), automatically grouped by day.

• Calendar: Select the source calendar.
• Custom Text: Content for when no events are found.

Next Upcoming Event Block

Highlights the single immediate next event with a live, ticking countdown timer (Days, Hours, Minutes, Seconds).

• Live Countdown: Automatically calculates and displays the time remaining until the event starts.
• Smart Filtering: Automatically starts to countdown to the next event once current event is at least 25% in progress.

Google Calendar Embed Block

Renders the standard Google Calendar iframe.

• Calendar: Select the source calendar.
• Dimensions: Set the width and height of the iframe.

Stale Data Prevention

To ensure users always see the correct information even when Drupal's Internal Page Cache or a CDN (like Varnish) is active, this module employs a hybrid server/client-side strategy.

This Week's Events Block

1. Over-fetching (PHP): The block fetches and renders two weeks of event data (the current week and the next week) into the HTML.
2. Timestamping: Each week container is tagged with data-week-start-timestamp and data-week-end-timestamp.
3. Client-side Pruning (JS): A lightweight JavaScript script checks the browser's current time against these timestamps. It automatically hides the old week and displays the new week as soon as the transition occurs (e.g., on Monday morning), even if the cached HTML is several days old.

Upcoming Events Block

1. Buffer Fetching: The block fetches extra events (defined by a buffer constant) beyond the configured limit.
2. Client-side Pruning: JavaScript hides individual event items that have passed their end time.
3. Dynamic Header Relabeling: If day grouping is enabled, the JavaScript re-evaluates the group headers (e.g., "Tomorrow", "This Week") based on the client's current time.
4. Local HTML Caching: To prevent a "flash" of old layout during processing, the script stores the final processed HTML in the browser's localStorage (keyed by the block's specific configuration). On subsequent page loads, the script instantly injects the cached HTML, ensuring a smooth, instantaneous experience. The cache is automatically cleared and regenerated every day.

COMPARISON WITH OTHER MODULES

There are several other modules in the Drupal ecosystem that interact with Google Calendar. Here is how Google Calendar Events differs:

• GCal Events (D7): This module is the spiritual successor to the popular Drupal 7 module. We have completely rewritten it for modern Drupal (10/11) and added advanced features like the Next Event countdown, "This Week" grouping, and robust performance strategies.
• Google calendar entity: This is perhaps the closest module to ours in terms of intent, but it takes a different architectural approach. Instead of providing flexible, ready-to-use blocks, it allows calendar listings to be inserted as entity references. Our module focuses on providing highly configurable, high-performance blocks that can be placed anywhere in your layout without needing to modify your entity structure.
• Date iCal: Focuses on using Feeds to import events as entities into the site and displaying them via Views. This is a powerful but heavy approach that requires database storage for every event.
• Google calendars: Provides integration for importing calendars into a custom table, often requiring the Migrate API to create nodes. It is designed for those who want to "own" the event data as nodes on their site.
• Google calendar import: A minimally maintained module that provides a way to import events from public calendars into Drupal entities.
• Google calendar service: Focuses on two-way synchronization, allowing events created in Drupal to be synced back to Google. Our module is focused on the display side, making it much lighter and easier to set up for most use cases.
• Google API PHP Client: This is just an API for developers to code against. It provides no user interface or blocks out of the box.

Why use this module?
If you want a lightweight, performant way to display your Google Calendar events in beautiful, themeable blocks without the complexity of importing hundreds of nodes into your database, this is the right choice. Our module's focus on user experience—including live countdowns and smart caching to prevent stale data—makes it the most modern and feature-rich option for event display.

Theming

The module provides several Twig templates that can be overridden in your theme:

• block--google-calendar-events-block.html.twig: Base wrapper for event blocks.
• upcoming-events-block.html.twig: Template for the "Upcoming Events" block.
• this-week-events-block.html.twig: Template for the "This Week's Events" block.
• next-upcoming-event-block.html.twig: Template for the "Next Upcoming Event" block.
• google-calendar-embed-block.html.twig: Template for the iframe embed.

Most blocks provide an events variable, which is an array of Event objects. Key methods available on the Event object:

• {{ event.title }}
• {{ event.description }}
• {{ event.location }}
• {{ event.startDateTime|date('Y-m-d H:i') }}
• {{ event.endDateTime|date('Y-m-d H:i') }}
• {{ event.htmlLink }} (Link to the event on Google Calendar)

Support development on this module

A lot of hard work and dedication has gone into developing this module. If you find it helpful and would like to support ongoing development, consider buying me a coffee! Your support helps ensure that I can continue enhancing and maintaining this module for everyone. Thank you for your generosity!

Troubleshooting: Caching Issues

If you notice that anonymous users are seeing stale event data (e.g., the "Next Upcoming Event" block still shows an event that has already started or finished), this is likely due to a known limitation in Drupal core's Internal Page Cache.

The Internal Page Cache often ignores the specific cache duration (max-age) bubbled up by individual blocks and instead caches the entire page for a default duration (often 1 hour or permanent). This causes the page to serve old content even if the Google Calendar Events module has refreshed its data.

Solutions

1. Install the Page Cache Max-Age Bubbling module: This helper module ensures that the lowest max-age on the page (e.g., from your event block) is correctly respected by the Internal Page Cache and external proxies.
   • Page Cache Max-Age Bubbling
2. Configure External Cache Correctly: If using Varnish or a CDN, ensure they are configured to respect the Cache-Control: max-age header.

For more technical details on this Drupal core behavior, see:

• Internal Page Cache ignores max-age bubbled metadata (#2352009)
• Common Max-Age Pitfalls with Drupal Cache (Lullabot).

Development

Running Tests

This module includes a suite of PHPUnit tests (Unit tests).

To run the tests:

phpunit -c phpunit.xml.dist ./tests

Code Coverage

To generate a code coverage report (requires Xdebug):

phpunit -c phpunit.xml.dist ./tests --coverage-html ./coverage-html