SDAweb Calendar Sync for Google Calendar

Description

SDAweb Calendar Sync pulls events directly from the Google Calendar API and renders them on your site through a Gutenberg block, a shortcode, or a classic widget. All three share one render pipeline so output is identical regardless of how you insert a calendar.

Six views, one render pipeline

  • List / Agenda — chronological, optionally grouped by day, week, or month
  • Month grid — classic 7×6 calendar with multi-day event ribbons spanning across cells, today highlight (cell or whole-column style), optional ISO 8601 week-number column, and per-feed pastel chips
  • Card grid — upcoming events as styled cards, responsive
  • Week — 7 day columns, today highlighted
  • Day — single-day agenda
  • Mini-month — compact dot-density grid for sidebars and widgets, with a tap-to-expand event panel showing today + next upcoming events and a “Load more” button

All views share the same data layer, the same CSS-variable system, and the same accessibility baseline. Switch between them with one setting, or expose a visitor-facing view-toggle pill so visitors can switch themselves.

Smart UX out of the box

  • Hover popover on event chips (Month, Week, Mini) — a floating card with date, time, location, calendar, recurrence summary, and a click-through link. Desktop hover + keyboard focus only; touch users keep direct click-through.
  • Mobile auto-degrade Month Mini — the full grid is hidden under ~600px and replaced with the compact Mini-month view; one wrapper, two layouts, no JS swap.
  • ICS subscribe dropdown — one-click hand-offs to Google Calendar (web), Apple Calendar / Outlook (webcal), Android Google Calendar app (intent), and Copy-link with toast confirmation. Mobile becomes a bottom sheet.
  • Live search + jump-to-date picker — optional chrome controls for visitors who want to filter or navigate quickly.
  • Multi-day event ribbons — week-spanning bars with arrow indicators when an event continues beyond the visible row.
  • Recurring event indicator — small ↻ icon with cadence summary in the tooltip (“Repeats weekly until 31 December 2026”).
  • Per-display locale override — render the calendar in a specific language (e.g. nb_NO) even when the site language is English.

Two authentication paths

  • API key — for calendars marked “Make available to public” in Google Calendar. One field, paste, done.
  • Service Account JSON — for private calendars without per-user OAuth. Upload the JSON, share the calendar with the service-account email, you’re set.

Credentials are encrypted at rest using a key derived from your site’s authentication salt. They are never echoed back into the admin UI — only the masked value and (for service accounts) the public service-account email are shown.

Theme-aware out of the box

The plugin reads your active theme’s theme.json color palette and uses your primary, accent, foreground, and background colors automatically. Per-display overrides let you set custom primary, accent, today-highlight, and link colors and force light/dark mode without touching code. Every design token is exposed as a CSS custom property so a developer can fully restyle the calendar from their theme stylesheet.

Five built-in theme presets

One-click coordinated colour bundles: Default (clean blue), Warm earth (cream + deep red), High contrast (solid black on white for AAA-stricter sites), Forest (deep green), Sunset (warm coral + amber).

Accessibility built in

WCAG 2.2 AA baseline with several AAA touches:

  • Live contrast warnings on every colour picker — the admin UI shows the WCAG ratio against both light and dark surfaces with pass/fail markers as you choose colours
  • Automatic high-contrast overlay via prefers-contrast: more
  • Focus-visible halo: a 4px white ring behind the primary outline so focus stays visible against any chip background
  • prefers-reduced-motion honored everywhere
  • ARIA roles and labels on the month grid, navigation, popovers, and view-toggle
  • Semantic HTML throughout
  • RTL-aware via CSS logical properties
  • Tabular numerals for day numbers and time labels so single- and double-digit values don’t drift

Built for the WordPress.org standard

  • Block editor first-class — server-side rendered, ServerSideRender preview, all the standard InspectorControls
  • Shortcode and classic widget on the same render pipeline
  • No bundled core libraries (no jQuery on front-end, no Guzzle, no Carbon, no Monolog)
  • No third-party authentication relay — your credentials only ever talk directly to googleapis.com
  • Translation ready via translate.wordpress.org once the plugin is published and indexed (no bundled .po/.mo — WordPress auto-loads locale files into wp-content/languages/plugins/ per the WP Plugin Handbook), plurals via _n(), JS strings via wp_localize_script
  • Free and GPLv2

For developers

Extension hooks are documented in docs/hooks.md inside the plugin folder. The first-release set includes filters for event data, event URLs, query args, cache TTL, render output, palette resolution, plus actions for refresh and uninstall lifecycle.

Third-Party Services

This plugin connects to the Google Calendar API to retrieve events from calendars you configure.

  • Service: Google Calendar API v3
  • Website: https://developers.google.com/calendar
  • Terms of Service: https://developers.google.com/terms
  • Privacy Policy: https://policies.google.com/privacy

Data sent: the calendar ID(s) you configure, plus either your API key or a JSON Web Token signed with your service account credentials. Event data is returned to your server and cached locally as WordPress transients. No event data is sent to any third party.

The ICS subscribe feature, when enabled, links visitors directly to Google’s public iCal feed (calendar.google.com/calendar/ical/.../public/basic.ics) — the plugin does not proxy or store that data.

Blocks

This plugin provides 1 block.

  • SDAweb Calendar Display events from one or more Google Calendars. Choose a saved display or configure inline.

Installation

  1. Upload the plugin to your /wp-content/plugins/ directory, or install it from the Plugins screen in WordPress.
  2. Activate the plugin.
  3. Go to Settings SDAweb Calendar Sync to add your first calendar.
  4. Choose API key (public calendars) or Service Account (private calendars), follow the in-app setup guide, save.
  5. Create a display, choose a view, and copy its shortcode — or insert the SDAweb Calendar block in a page.

FAQ

Do I need a Google account to use this plugin?

You need a Google Cloud project to generate either an API key (for public calendars) or a service account (for private calendars). The plugin’s Help tab walks you through both setups in 7–8 steps each. Setup is one-time per site.

Does this plugin send my data anywhere other than Google?

No. Calendar data is fetched directly from googleapis.com using the Google Calendar API. The plugin does not contact any SDAweb-controlled servers, analytics endpoints, or third-party relays. There is no telemetry.

Can I display a private (non-public) calendar?

Yes. Use the Service Account authentication option. The plugin shows you the service account email; share your private calendar with that email in Google Calendar’s sharing settings, and the plugin can read it.

How often does the plugin refresh events?

A WP-Cron job refreshes registered calendars in the background every 15 minutes. Cache lifetime is configurable upward in the plugin settings (15 minutes is the enforced minimum). You can also click “Refresh now” on any calendar in the admin to fetch immediately.

Does it work with caching plugins?

Yes — the calendar HTML is part of the page output, so any page-cache plugin caches it like any other content. The cache will refresh on its own schedule. If you need immediate refresh after a calendar change, purge the page cache.

Can I add multiple calendars to one display?

Yes. Each display picks one or more registered calendars and merges them. Events are color-coded by calendar. A multi-feed legend strip can be enabled above the events; chips can be styled solid (single-feed) or pastel (multi-feed legibility).

Will it work with my theme?

The plugin reads your active theme’s theme.json color palette automatically, so calendar colors match the site by default with zero configuration. If you use a classic theme without theme.json (or want to override), every color is exposed as a CSS variable that you can override from your theme stylesheet. Five built-in theme presets give you coordinated palettes with one click.

Is the plugin accessible?

Yes — built-in. WCAG 2.2 AA baseline includes prefers-reduced-motion and prefers-contrast: more support, :focus-visible outlines with a white halo (visible on any background), ARIA labelling on the month grid, navigation, popovers, and view-toggle, semantic HTML throughout, RTL-aware via CSS logical properties, and live contrast warnings in the colour-picker UI as you choose values.

Can I show the calendar in a different language than the rest of the site?

Yes. Each display has an optional Locale override field — set it to nb_NO, sv_SE, etc. and that calendar renders weekday names, month names, and built-in labels in that language regardless of the site’s language. Useful when an English site hosts Norwegian-audience content.

Where are the extension hooks documented?

In docs/hooks.md inside the plugin folder. The plugin commits to keeping documented hooks stable within a major version.

Reviews

There are no reviews for this plugin.

Contributors & Developers

“SDAweb Calendar Sync for Google Calendar” is open source software. The following people have contributed to this plugin.

Contributors

Changelog

The most recent releases are listed here. The complete history is in
docs/CHANGELOG.md bundled with the plugin.

0.8.6

  • Fix: Service-account token-exchange success no longer writes to the PHP error log unconditionally. The success path is now gated on WP_DEBUG; on busy sites this was logging one line every ~55 minutes even when everything was working correctly. Token-exchange failures and API errors continue to log unconditionally so real problems are always surfaced.
  • Fix: Upgrade notice for 0.8.3 in readme.txt exceeded WordPress.org’s 300-character limit (Plugin Check upgrade_notice_limit warning). No code change.

0.8.5

  • New: Delete button on each row in Tools Backups. Snapshots could previously only be removed by capturing three new ones to push them out of the retention window — fine for routine pruning, awkward when a single test snapshot wanted to go. The Delete button now removes one specific snapshot immediately (confirm dialog first; record is gone from the sdaweb_gcal_backups option). Frees a retention slot so the next pre-import/manual snapshot won’t prune a newer one to make room.

0.8.4

  • Fix: Solid Month chips lost their auto-resolved text color on hover. The general .sdaweb-gcal a:hover rule in front.css set a hover color that cascaded into the chip’s <a> because the more specific .sdaweb-gcal-month__event a:hover rule only set text-decoration — same specificity, no color reset, so the general rule’s color property won by cascade. Result: a chip whose Auto mode picked dark text correctly would flip to the link/accent color on hover, often dropping back below the WCAG threshold the Auto mode was protecting. Fix pins the hover color to inherit and adds a subtle text-underline-offset: 2px for breathing room. Week/Day chips deliberately keep their primary-color hover (different chip design — surface backgrounds, hover affordance comes from the color change).

0.8.3

  • New: Solid chip text color option on the display edit screen (Appearance Event chip style Solid chip text color). Three modes: Auto (default) computes the WCAG relative-luminance contrast for white vs dark text against each chip background and picks the higher-contrast side; Always light (white) preserves the pre-0.8.3 behaviour; Always dark forces dark text. Fixes a long-standing readability issue where Solid chips with mid-luminance feed colors (greens like #16a34a, yellows, mints) rendered as white text on a too-light background and the title “faded into” the chip in the tiny month-grid footprint. Existing displays render unchanged on first load (Auto picks white for the same dark reds/blues/teals that white was already being used on); only chips whose feed color previously failed AA against white will switch to dark text.

0.8.2

  • New: Upcoming view exposes three new per-display title appearance controls — Title size (Small / Medium / Large / X-Large), Title weight (Normal / Medium / Semi-bold / Bold), and an Uppercase title toggle. Useful when the surrounding container’s headings (sidebar widget titles, footer column headers) use a different weight/case than the plugin’s default 15px / 500, so the “Fra kalenderen”-style title can be tuned to blend in without site CSS overrides. Existing displays render unchanged — defaults match the previous hard-coded values.
  • Change: The Upcoming view’s “See all ” link now always opens in the same window, regardless of the display’s Link target setting. The link points to the site’s own calendar page; opening a same-site link in a new tab is a UX anti-pattern (breaks the back button, loses navigation context). Per-event URLs (typically off-site) continue to honour the Link target setting.

0.8.1

  • Fix: View-toggle / focus-date / “+N more” / date-jump URLs are now scoped to the calendar instance whose control was used — they no longer bleed into every other calendar on the page. Previously, switching the main calendar to Month or Day view also flipped any other calendar instance on the page (footer widgets, sidebar instances) into the same view. A footer “Upcoming” widget on the same page as a Month-view calendar would render as a cramped Month grid in the narrow footer column, and looked broken. Same root issue for ?sdaweb_gcal_focus= — every calendar on the page jumped to the same date. Fix: every navigation URL now carries sdaweb_gcal_id=<display-slug> and the renderer ignores the override unless the URL’s id matches the current display.

0.8.0

  • New: Month-view “+N more” indicator is now interactive (was a non-clickable <li> — a real a11y gap; keyboard users and screen readers couldn’t reach it). New per-display option Day overflow (“+N more”) under “Month view options” with two modes: popover (default) opens an in-place panel listing the day’s full event list; day turns “+N more” into a link that loads the Day view for that date. Popover ships with focus management (Esc, click-outside, focus restoration), aria-haspopup/aria-expanded, and role="dialog". Day-link mode ships zero JS.
  • New month_overflow_action shortcode attribute / monthOverflowAction block attribute (values: popover | day).

0.7.4

  • Fix: Multi-day events in the Cards view now render with a date range in the date column (“4–8 / MAI / man–fre” for same-month, stacked “30 APR 5 MAI” for cross-month) instead of showing only the start day. Previously a 5-day event like “Class trip Monday–Friday” looked indistinguishable from a single-day event in cards.
  • Fix: Cards view with card_grouping = day now expands multi-day events into every day they cover, matching Week and Mini view behaviour. Previously a Monday–Friday event only appeared under Monday’s section. Week and month grouping keep the simpler “appear once at the start group” behaviour — the new date-range badge signals the span without multiplying cards across groups.
  • All-day handling honours Google Calendar’s exclusive-end-date convention (a “Mar 5–7” event arriving as end=Mar 8 is correctly bucketed and labelled as Mar 5–7 inclusive).

0.7.3

  • Docs: Moved CHANGELOG.md from the plugin root to docs/CHANGELOG.md. Plugin Check’s unexpected_markdown_file rule (severity 9 WARNING) flags any non-readme .md file at the plugin root.
  • Docs: Trimmed this Changelog section (per Plugin Check’s 5000-character cap). Full history is in docs/CHANGELOG.md.

0.7.1

  • Admin: Edit Display form fields no longer overflow under the sticky Live preview pane on the right. <select> elements had no width rule and auto-sized to their longest option text, clipping trailing characters behind the preview. Selects, plus input[type="number" | "url" | "date"], now share the same width: 100%; max-width: 520px cap as text inputs.

0.7.0

  • New: “Card grouping” display option — groups cards in the Cards view under day, ISO week, or calendar month section headings, with a per-section event count. Defaults to off; existing displays render byte-identically until you opt in. Configured per display under “Card view options” in the admin, or via the card_grouping shortcode attribute / cardGrouping block attribute.

0.6.10

  • Fix: Per-display label overrides (“Today”, “Tomorrow”, “All day”, etc.) are now honored by the shortcode/block pipeline. Same root cause as 0.6.9 — Shortcode::defaults() was missing the labels key.
  • New: Gutenberg block now exposes “Event color override” as an Inspector control. Block users in inline mode (no saved display selected) had no UI to set the override before.
  • Fix: Admin Live Preview now correctly renders the Upcoming view when configured. Was silently falling back to List.