Description
SDAweb Calendar Sync turns any Google Calendar into a polished, on-brand events display on your WordPress site — without duplicate data entry. Keep scheduling in Google Calendar the way you already do; the plugin pulls those events in and keeps your site in sync automatically.
It’s for anyone who already runs their events in Google Calendar and wants them to look like a native part of their site instead of an embedded iframe — businesses, teams, venues, clubs, communities, and organisations of every kind.
Insert a calendar with a Gutenberg block, a shortcode, or a classic widget. All three share one render pipeline, so the output is identical however you add it.
Six ways to show your calendar
- 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
Switch between views with one setting, or expose a visitor-facing view-toggle pill so visitors can switch themselves. Under the hood every view shares the same data layer, the same CSS-variable system, and the same accessibility baseline.
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, so visitors get the full event detail without leaving the page. Desktop hover + keyboard focus only; touch users keep direct click-through.
- Mobile auto-degrade Month → Mini — below ~600px the full grid is replaced by the compact Mini-month view, so phone visitors get a clean, tappable calendar with no extra work from you. One wrapper, two layouts, no JS swap.
- ICS subscribe dropdown — one tap to add your events to a visitor’s own calendar: 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 so visitors can 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 a plain-language cadence summary in the tooltip (“Repeats weekly until 31 December 2026”).
- Per-display locale override — render a calendar in a specific language (e.g. nb_NO) even when the site language differs, so you can run a localized calendar on a site that’s in another language.
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-motionhonored 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 intowp-content/languages/plugins/per the WP Plugin Handbook), plurals via_n(), JS strings viawp_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, serves a self-hosted iCalendar (.ics) feed from your own site — built from the same calendar data already fetched via the Google Calendar API above — so subscribers can add it in Google Calendar, Apple Calendar, Outlook, or any other app that supports calendar subscriptions. No data is sent to any third party beyond the Google Calendar API connection already disclosed.
Installation
- Upload the plugin to your
/wp-content/plugins/directory, or install it from the Plugins screen in WordPress. - Activate the plugin.
- Go to Settings → SDAweb Calendar Sync to add your first calendar.
- Choose API key (public calendars) or Service Account (private calendars), follow the in-app setup guide, save.
- 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.
Can I show booked appointments without the booker’s name?
Yes. Under Calendars → Edit calendar, tick “Handle booked appointments and private events” and choose “Show as Booked” for booked appointments. Only the time is shown; the name, email, description and location are removed before anything is stored. Open booking slots cannot be shown: Google does not share them with any plugin.
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.
Changelog
The most recent releases are listed here. The complete history is in
docs/CHANGELOG.md bundled with the plugin.
0.27.1
- Help: new paragraph “Who can book” in “Booked appointments and privacy”. A Google Calendar booking page is open to anyone with the link, and the paragraph lists what Google offers to limit bookings.
- Help: how to add your own booking link, as a button on the page or with the display’s footer link. No change in behaviour.
0.27.0
- New calendar setting “Privacy: booked appointments and private events” (Calendars → Edit calendar). Off by default, so nothing changes until you tick “Handle booked appointments and private events” for a calendar.
- Booked appointments from a Google Calendar booking page can be shown as in Google, shown only as “Booked” (time only, no name, description, location or link), or hidden. A calendar that holds only bookings can show every event as “Booked”.
- Private and busy-only events can be shown as “Booked” instead of being hidden. The word “Booked” can be replaced with your own text.
- The booker’s name and email are removed before anything is stored, so they never reach your pages, popups or the subscribe feed.
- Tools → Diagnostics shows how many bookings were recognised in the last fetch. Developers can mark other events as bookings with the new
sdaweb_gcal_is_bookingfilter. - Fixed: in the settings, fields that depend on another setting showed both an “active” and an “inactive” label at the same time. Only the one that applies is shown now.
0.26.2
- Help: the “Booked appointments and privacy” section is now worded in general terms for any booking tool that adds its bookings to your Google Calendar. No change in behaviour.
0.26.1
- Clearer settings: the two description checkboxes (“Show description” and “Keep descriptions out of hover text, popups and the subscribe feed”) could look as if they contradicted each other. They are now one question, “Event descriptions”, with four answers: everywhere; hover text, popup and subscribe feed only (not in the event list); event list only; or nowhere (recommended for calendars with booked appointments). Your current setting is pre-selected, so nothing changes for visitors. The block editor has the same four choices; shortcodes work as before.
- Help and privacy policy text updated to match.
0.26.0
- New privacy setting: “Keep descriptions out of hover text, popups and the subscribe feed” under Displays → Event row content, right below “Show description”. Until now an event’s description was always part of the hover tooltip, the hover popup and the subscribe feed, even with “Show description” off. When ticked, the description appears only where “Show description” puts it. Recommended when descriptions can hold personal details, such as the name and email address that Google adds to booked appointments. Off by default, so nothing changes until you tick it. Also available as a block setting and as
private_descriptions="1"in the shortcode. - Help: new section “Booked appointments and privacy”: how bookings from a Google booking page reach your site, why open booking slots cannot be shown, the recommended setup for school, business and free Gmail accounts, and how to keep the booker’s details off your pages.
- Privacy policy text: explains that booked appointments carry the booker’s name and email, and how the new setting keeps them off the page.