SemaCalendar shows shared Google Calendars on your website and lets visitors book an appointment. Events are managed in Google and the website only displays them; bookings are made on the website and, once confirmed, are written to the Google Calendar of whoever is being booked.
| Joomla | PHP | Current version | |
|---|---|---|---|
| 5.2+, 6.x | 8.1+ | Calendar API, service account | 1.0.0 |
1. Requirements
- Joomla 5.2 or later, or Joomla 6
- PHP 8.1 or later with the
opensslextension (signs the access to Google) - MySQL 8 or MariaDB 10.6+
- A Google account and a Google Cloud project with the Google Calendar API enabled (no fees)
- Joomla Scheduled Tasks – run by site visits, or better by the hosting's cron
2. Getting started
- Install the SemaCalendar package (System → Install → Extensions). It installs the component, the module, the scheduler plugin and the privacy plugin.
- Create a Google service account and upload its key to the server (chapter Access to Google Calendar).
- In Google Calendar, share the calendar with the service account's email.
- In the administrator open Components → SemaCalendar → Calendars, add the calendar and click Verify Access.
- Create the scheduled task SemaCalendar - sync of the calendars (chapter Scheduled task).
- Add a Calendar menu item or the SemaCalendar module.
- For booking, create Resources and Purposes and a Booking menu item.
3. Access to Google Calendar
The website signs in to Google with a service account – a technical account of a Google Cloud project. No signing in with a personal account and no consent screen: you simply share the calendar with the service account, just like with a colleague.
- In the Google Cloud console create a project (or use an existing one) and enable Google Calendar API in it.
- IAM & Admin → Service Accounts → Create service account. No roles are needed.
- On the service account open Keys → Add key → Create new key → JSON. A file with the key is downloaded.
- Upload the file to the server. The recommended place is outside the web root (for example one level above
public_html); enter its path in Options → Google Calendar → Key path.
If you leave the path empty, the website looks for the key inadministrator/components/com_semacalendar/keys/gcal.json. That folder is protected against download, but uninstalling the component deletes it together with the key. - Use the service account's email (
…@….iam.gserviceaccount.com, also in the key file asclient_email) when sharing calendars.
The Time zone in Options sets the time in which working hours and all-day events are calculated. The default is the website's time zone.
Watch out for
- The key is the password to your calendars. Don't send it by email and don't leave it unprotected in the web root.
- The component dashboard warns you when the key is missing or can't be read.
4. Calendars
Components → SemaCalendar → Calendars are the calendars the website shows.
- In Google Calendar open the calendar's Settings and sharing, and under Share with specific people add the service account's email. For display, See all event details is enough.
- Under Integrate calendar copy the Calendar ID (an email address or
…@group.calendar.google.com). - In the administrator click New, fill in the title and the Google calendar address (that ID) and save.
- Tick the calendar and click Verify Access. The message tells you whether Google shows the calendar to the service account.
Visitors see:
| option | what is on the website |
|---|---|
| Full details | title, time, location, description and an event page of its own |
| Title and time | just the title and time, no location or description |
| Busy only | the time as "Busy", nothing about the event |
Access (a Joomla access level) decides who sees the calendar at all – for example logged-in members only.
Days back and Days ahead (the Synchronisation tab) set which period the website keeps. The window moves on by itself.
Watch out for
- Events are not edited in the administrator – Google is the source of truth. Make the change in Google Calendar and the website picks it up at the next sync.
- Event descriptions from Google are cleaned on the website: links and basic formatting stay, scripts and embedded frames don't.
- Deleting a calendar in the administrator deletes only its copy on the website, the Google Calendar is not touched.
5. Scheduled task
Events are loaded into the website by a scheduled task, not when a page is opened – that keeps the website fast and away from Google's limits.
- System → Scheduled Tasks → New → SemaCalendar - sync of the calendars.
- Interval 5–15 minutes. Leave Only calendar no. at 0 (all).
- Save. The Joomla scheduler runs either on site visits (Lazy Scheduler) or from the hosting's cron – on a website with little traffic we recommend cron.
The same task also releases unconfirmed bookings, writes confirmed bookings to Google when the first attempt failed, and anonymises old bookings.
To sync right now, use Sync Now in the Events list or Sync on selected calendars.
6. Overview and events
The Overview (the component dashboard) shows events and bookings for the next 14 days and the sync status of every calendar – when it ran, how many events it holds and whether the calendar could not be loaded.
Events is the list of everything the website has taken over from Google, with a filter by calendar and time. Read only.
7. Calendar on the website
Menu item of the type SemaCalendar → Calendar:
- Calendars – which calendars the page shows (empty = all published ones the visitor may see).
- Default view – month, week or list. Phones always get the list.
- Week from / to (hour) – the hour range of the week view.
- Events without JavaScript – how many upcoming events the page lists for search engines and browsers without JavaScript.
An event in a calendar with Full details visibility has its own page with the description, the location and structured data for search engines.
The SemaCalendar module shows upcoming events (layout Default) or a small month (layout month). Calendar page is the Calendar menu item the module links to and under which event pages open.
The look can be overridden in the template (html/com_semacalendar/…, html/mod_semacalendar/…, html/layouts/com_semacalendar/booking/calendar.php).
8. Appointment booking
Booking rests on two things:
- Resource – who or what is booked: a person, a room, a service. It has working hours and, optionally, its own Google Calendar.
- Purpose – what is booked: length, location, gap between bookings and which resources accept it.
Resources
Components → SemaCalendar → Resources → New:
- Working hours – days 1 (Monday) to 7 (Sunday), a day range with a hyphen, times with a comma, groups with a semicolon. Example:
1-5 09:00-12:00,13:00-17:00; 6 09:00-12:00. - Google calendar address – optional. Busy times in this calendar block slots and a confirmed booking is written into it. The calendar must be shared with the service account with the right Make changes to events. Without a calendar, bookings stay on the website only.
- E-mail for bookings – where a copy of every confirmed and cancelled booking goes.
- Notice (hours) – at least how many hours in advance a slot can be booked.
- Bookable ahead (days) – how far ahead slots are offered.
Verify Access on a resource checks that the website can see into its calendar.
Purposes
Components → SemaCalendar → Purposes → New: title, Length (minutes), Gap after (minutes) (time for travel or preparation around each booking), Place (goes into the emails and the event) and Resources. A purpose without a resource can't be booked.
The Code is created from the title. Don't change it on a purpose a menu item points to.
Booking page
Menu item of the type SemaCalendar → Booking. Purpose and Resource narrow the page to one purpose or resource; empty = the visitor chooses.
The visitor picks a day and time in the calendar of free slots, fills in name, email and optionally phone and message, agrees to the data processing and passes the captcha.
How a booking goes
- After the form is sent, the slot is held (Options → Booking → Hold time (min), 30 minutes by default) and the visitor gets an email with a link.
- On the page from the link they confirm the booking. Only a confirmed booking is written to the resource's Google Calendar; the visitor gets a confirmation with an invitation (
invite.ics) for their own calendar and the resource gets a copy. - When the hold time runs out, an unconfirmed slot goes to the next visitor and the scheduled task deletes the booking.
- From the link in the confirmation the visitor can cancel the booking. It disappears from the resource's calendar, the visitor gets a cancellation (
cancel.ics) and the resource a copy.
Two people who pick the same slot don't both get it: availability is checked when the form is sent and again on confirmation.
Bookings in the administrator
Components → SemaCalendar → Bookings – a list with filters by status, resource and purpose.
- Confirm – confirms the booking on the visitor's behalf (for example when the slot was agreed by phone). The visitor gets the confirmation with the invitation.
- Cancel booking – cancels it; the visitor gets the cancellation.
- A cancelled booking can be trashed and deleted.
Booking options
Options → Booking: Hold time (min), Captcha (default = the captcha from the website's Global Configuration), Consent text next to the form's checkbox – add a link to your privacy policy to it.
Emails
The five emails (booking confirmation request, booking confirmed, booking cancelled, copy to the resource about a new and about a cancelled booking) are edited in System → Templates → Mail Templates, filter SemaCalendar.
Watch out for
- A form without a captcha is open to bots. Enable a captcha in the website's Global Configuration or in the component options.
- A resource or purpose that has bookings can't be deleted – leave it in the trash.
- When Google is unavailable, the booking is confirmed anyway and the scheduled task writes it to the calendar later. The booking list then shows "Not in the calendar of the resource yet".
9. Personal data protection
A booking holds the visitor's name, email, phone and message.
- Export and erasure requests – the Privacy - SemaCalendar plugin joins Users → Privacy → Requests. Export adds the bookings with the request's email. Erasure first cancels upcoming bookings (without email) and then anonymises all of them.
- Anonymisation removes the name, email, phone and message, from the event in the resource's Google Calendar too. Time, purpose and resource stay for the overview; the booking list shows "Anonymised" instead of the contact.
- Retention – Options → Booking → Anonymise bookings after (months), 24 by default. The scheduled task anonymises bookings that ended earlier. 0 = never. Set the period according to your data processing policy; 24 months is only the default, not legal advice.
The component doesn't deal with cookie consent – it sets no cookies for measurement.
10. Measurement
If the SemaTrack (Sema SST) measurement plugin is on the website, the component reports every booking a visitor confirms as a booking_confirmed event with the purpose and resource – without personal data. A booking confirmed in the administrator is not reported, it is not a visitor's conversion. Whether the event goes on to GA4 or Meta is set in Sema SST.
Turn it off in Options → Booking → Events for Sema SST. Without the plugin nothing happens.
11. Updates and uninstalling
Updates arrive through System → Update with the download key from SemaHub (System → Update Sites, SemaCalendar → Download Key).
Uninstalling the package deletes all the component's tables (calendars, events, resources, purposes, bookings) and the default key folder. Events in Google Calendars stay.