Google Calendar import plugin provides support for Google Calendars in Smart Countdown version 3.0 or later. It pulls events from selected Google calendar and adds them to Smart Countdown events queue so that countdown/count up is switched automatically to the next event in queue.

Once installed and enabled the plugin adds a new pane ("Google Calendar Bridge") to Smart Countdown 3 module settings screen. You have to install and configure Smart Countdown 3 module prior to installing Google Calendar import plugin.

Both the module and your Google account have to be configured before the calendar can be connected with Smart Countdown.

The module below is connected to a test public calendar. Default timezone for this calendar is CET. You can check it in native Google Calendar view.

Import events from a private calendar using OAuth authentication method. Colour filter is set so that only "default calendar" and "red" colour events are imported.

Updated version available for purchase - 4.90€

Make payments with PayPal - it's fast, free and secure

Configuration Overview

The configuration required consists of two basic steps: Google Calendar API configuration and Smart Countdown 3 configuration. If you are using Google Calendar in shared mode you probably have everything already set up so you should login to https://console.developers.google.com/ with your google account, go to the project where you have Calendar API enabled and take note of your current credentials and calendar ID. Then you can go directly to step 3 - module configuration.

If your Google calendar is not shared and / or you don't have projects in Developers Console yet, please continue reading.

Prepare Google Calendar API

Step 1

First you have to create a project in Google Developers Console and enable Calendar API.

Figure 1

If you already have existing project(s) you can enable Calendar API for one of your projects (if not enabled yet). Choose a project from the list, in the sample below we will be working with "Smartcalc" project created on previous step.

Figure 2

Now we have to add and enable Calendar API in our project. Make sure you see your current project at the top of the window as shown below. Click "Library" menu.

Figure 3

Search for "Calendar" in API library.

Figure 4

Select "Google Calendar API" and enable it.

Figure 5

 

After you complete these steps Calendar API should be listed in enabled APIs.

Figure 6

Step 2

Now we have to create API credentials. Select "Google Calendar API" from the list to open Calendar API configuration.

Figure 7

Click "Create credentials". Google calendar import plugin supports two authentication modes: API key and OAuth. Each one has its pros and contras and you have to choose the mode that suites better.

API key mode.

Pros:

  • Easy to setup.
  • Event title displayed in module can link to event details in native Google calendar view.

Cons:

  • Only public calendars are supported.
  • Filtering by event color is not supported.

OAuth mode.

Pros:

  • Private calendars are also supported.
  • Events can be filtered by color.

Cons:

  • Somewhat harder to setup.
  • Event title displayed in module cannot link to events details view.

API key mode setup

Figure 8

In the sample above we create an API key.

Figure 9

API key should be listed in credentials.

Figure 10

Next we have to edit recently created API key.

Figure 11

Here we can change API key name and also restrict key access. Please, keep in mind that Smart Countdown 3 calls Google Calendar API from server, that is why "HTTP referrers..." option will not work. If you are concerned about API key restrictions you should choose "IP addresses" option. In the sample above we are testing plugin locally so we have added 127.0.0.1 to allowed IP list.

There is also an option to restrict key access by API type.

Figure 12

Save your API key configuration to return to credentials list.

Figure 13

Take note of API key. You will need it later in Smart Countdown 3 settings for API key authentication.

OAuth mode setup 

Choose "Service account key" option when creating new credentials.

Figure 14

Choose key options as shown below. Important settings are marked with red box.

Figure 15

Credentials JSON file should be automatically saved to you local disk after you click "Create". Keep this file in a safe location. JSON key file can be saved only once when service account is created.

JSON key file will be required later in Smart Countdown 3 module settings for OAuth authencication.

Figure 16

Keep note of your service account email, you will need it later for private calendar sharing settings.

Prepare Your Calendar

Step 3

Login to your gmail account and go to Calendar application. We will create a new calendar to use as a source of events for Smart Countdown. If you prefer using an existing calendar (which normally will be the case) you can skip calendar creation step and go directly to calendar configuration. Just make sure that your existing calendar public / private status is compatible with authentication mode (API key / OAuth) chosen in Step 2.

We will create two calendars, public and private ones to illustrate required configuration.

Figure 17

Public calendar for API key access

Figure 18

We have to setup public calendar.

Figure 19

Scroll to bottom to see more.

Figure 20

Please take note of Calendar ID and time zone.

Private calendar for OAuth access

Figure 21

We have to setup private calendar.

Figure 22

Scroll down to see more.

Figure 23

Please take note of Calendar ID and time zone.

Important step - add service account email created earlier to "Share with specific people" list.

Figure 24

Finish Module Configuration

Step 4

Google Calendar Bridge plugin adds a new pane to Smart Countdown 3 settings.

The screenshot below is a sample - API key authentication.

Figure 25

OAuth authentication method sample.

Figure 26

Fields explanation:

  • Enabled - enable/disable the calendar connection. When disabled no events will be imported from Google Calendars.
  • Show Event Titles - choose how Google Calendar event titles should be displayed: appended to module generic text (e.g. "Time left to"), prepended or hidden (in the latter case only generic text will be displayed).
  • Link Event - make event title act as a link to event details view in native Google calendar (will work only if "API Key" authentication method is used). Available options: "Never Link", "Always Link", "Only be before event start", "Only while event is in progress".
  • Event Details - event date and location can be displayed along with event title. Choose which data to show: none of above, date only, location only or both. When event date and time is displayed and event timezone is not the default calendar timezone, the timezone title will be appended to the date.
  • Event Details Position - choose where event details are displayed: appended or prepended to event title. If "Event Details" option is set to "none" this setting will have no effect.
  • Event Details Style(s) - special style for event details. Add one or more CSS rules separated and ended with ; (semi-colon). These rules will be applied to date and/or location text only, e.g. you can use a smaller font here to make visual difference between event title and additional data.
  • Authentication Method - choose which authentication method to use when calling Google Calendar API. Depends on your calendar sharing configuration. Required credentials settings depend on the method shosen (see "for OAuth only" / "for API Key only" notes for some of the fields below).
  • Calendar ID - Google calendar ID. This is a required setting, refer to your calendar settings page in your google calendar web application.
  • All day events start time - virtual start time that will be used for counter value calculation (e.g. time left) relatively to events marked as "all day". A lot of real-life all day events do not start at midnight. You can choose a more meaningful value so that your site visitors are not confused when they see that "tomorrow's all day event" has already started when the check your site at 12:05 a.m.
  • Default Timezone - should be the same as the default Google Calendar timezone. If your Google Calendar and global Joomla server timezone use the same setting leave this option at "- Use Default -" value. This setting is only required to process "all day" events but recommended to be set correctly anyway.
  • Cache API Requests - Google Calendar API has its usage quota. It looks relatively high (you can check API usage statistics in Google Developers Console) but the module can make API usage less "agressive" caching events list receieved from Google in user's session. This cache will have a limited life-time, choose the option that meets your requirements. If events are not updated too often and/or a short delay before updates are reflected in Smart Countdown is not critical you may be fine with 10 minutes cache (maximum). Using cache will also make your pages load faster.
  • Debug API Calls - all plugin-related errors (missing configuration and API calls errors) are always logged to "/logs/scgcal.error.php" file. In order to make configuration easier you can enable visual error reporting - possible errors will appear in notification area of your Joomla frontend template. Do not forget to disable "Debug API Calls" once you have everything set up and in production environment!
  • API Key - Public access API Key (for API Key auth method only). Enter the value for Developers Console credentials screen. See documentation above.
  • Service Account Email - Service email address (for OAuth only). Enter the value from Developers Console credentials screen. See documentation above.
  • JSON Key File - current imported JSON key filename. For information only. This value will be reset when you switch to "API key" authentication method and save.
  • Import/Replace JSON Key - Upload JSON key file generated in Developers Console credentials view (for OAuth only). Only has to be done to initially import the key or when you wish to replace the key with a new one. This value will be reset when you switch to "API key" authentication method and save.

Filter Events by Colour

You have to fill in and save module settings before you can start configuring colour filters. If module configuration is compatible with colours filter a new field will appear at the bottom of "Google Calendar Bridge" pane in module settings.

color filter

Check one or more option checkboxes and save. Only events with checked colours will be imported into events queue in Smart Countdown 3. "Calendar Default" option selects events that have default colour (i.e. no individual colour set) - in your calendar view such events have the same colour as your calendar (global setting). Click helper buttons to quickly check / uncheck all options. If all options are unchecked "Calendar Default" will be implicitly activated on save. Checking all options will have the same effect as "no filtering".

Troubleshooting

Loading spinner appears for a while and goes away. Timer module is not showing.
  • Check that there are future events in connected Google calendar.
  • Enable "Debug API calls" option temporarily and check for error alerts when the page with timer is reloaded.
Some events are not imported.
  • If using event colour filter check that correct colours are selected in module options.
"Debug API calls" is enabled and error alert reads "Not Found".
  • Using private calendar - check that calendar sharing is setup correctly and your Google service account email is included to sharing list with at least "See event details" permissions.