Regardless of niche, adding a calendar plugin to your WordPress site is a great way to improve user engagement and retention. Creating such a plugin doesn’t take much effort because there are lots of cloud-based calendaring packages available today. Google Calendar is the most popular of them all, and it offers a free to use API.
In this tutorial, I’ll show you how to use the Google Calendar API to quickly create a WordPress calendar plugin that can display events from any publicly accessible Google calendar.
Prerequisites
To be able to make the most of this tutorial, you’ll need:
- PHP 7.0.32 or higher
- WordPress 4.4.2 or higher
- Composer 1.8.0 or higher
- a Google account
1. Creating a Google Project
You can use the Google Calendar API only after you’ve created an appropriately configured project on the Google Cloud Platform console. So log in to the console and, in the dashboard, press the Create button.
In the form that’s shown next, give a name to your project, change its ID if you want to, and press the Create button.
Once the project is ready, open the API library, select the Google Calendar API card, and press the Enable button to activate the API.
2. Creating a Service Account
Unlike most other Google APIs, the Google Calendar API doesn’t allow you to authenticate your requests using an API key. Instead, it expects an OAuth 2.0 authorization token.
To be able to generate such a token from the server you’re running WordPress on, you’ll need a Google service account. So go to the Credentials section, press the Create Credentials button, and select the Service account key option.
In the next screen, choose the New service account option and type in a name for the service account. In the Role field, select the Role Viewer option. This will give the service account read-only access to all your Google calendars.
Once you press the Create button, you’ll receive a JSON file containing a private key and a client ID. Save the file because you’ll need it later.
3. Creating a WordPress Plugin
To start creating the WordPress plugin, create a new directory called my-gcal-plugin inside the wp-content/plugins/ directory of your WordPress installation. You are free to use any other name for the directory. However, if you plan to share the plugin in the future, make sure that the name is unique in order to avoid conflicts with other plugins.
Inside the directory, create a PHP file named my-gcal-plugin.php and open it using a text editor.
For WordPress to recognize your plugin, this file needs to have a valid header comment. At the very least, the comment must specify the name of your plugin. However, I suggest including a short description and a version number too. So add the following code inside the file:
<?php /** * Plugin Name: My GCal Plugin * Description: Displays upcoming events from public calendars * Version: 1.0.0 */
If you save the file now and open the Plugins screen of your WordPress admin panel, you should be able to see your new plugin listed there. Click on the Activate link below it before you proceed.
4. Creating a Widget
To be able to display the output of your plugin in your WordPress site, you’ll need a custom widget. So, inside the PHP file, create a new class that extends the WP_Widget class. You can call it My_GCal_Widget.
class My_GCal_Widget extends WP_Widget {
}
Using the constructor of its parent class, you can specify the name of your widget, the CSS class it should use, and, optionally, give it a description.
public function __construct() {
parent::__construct('my_gcal_widget', 'My GCal Widget',
array(
'classname' => 'my_gcal_widget',
'description' => 'Shows events from a calendar'
)
);
}
By overriding the widget() method, you can specify what the widget displays. Leave this method empty for now.
public function widget($args, $instance) {
// More code here later
}
Lastly, don’t forget to register the widget by calling the register_widget() function. The best place to do so is inside a widgets_init hook callback. So add the following code at the end of the PHP file:
add_action('widgets_init', function(){
register_widget('My_GCal_Widget');
});
If you save the file and open the Appearance > Widgets screen of the admin panel, you should now be able to see the new widget listed there.
Drag and drop the widget anywhere inside the Sidebar section. This way, when the widget is ready, it will be able to show calendar data in your blog’s sidebar.
5. Installing the Google API Client
Now that you have a widget that’s ready to add content to your WordPress site, it’s time to start integrating it with the Google Cloud platform. There’s an official API client library available for PHP applications, and it offers lots of handy methods that allow you to interact with the Google Calendar API.
Because the library is available on the Packagist repository, the easiest way to install it is to use composer.
Run the following command inside your plugin directory to install the latest version of the Google API client:
composer require google/apiclient
The library will need the JSON file you downloaded in an earlier step. Therefore, copy the file to your plugin directory now.
Once the library and all its dependencies are installed, go back to your PHP file and load it by adding the following code right below the header comment:
require __DIR__ . '/vendor/autoload.php';
6. Initializing the Google Client
Before you try using the client, you must configure it using the JSON file. Start by creating a member variable called $client inside the My_GCal_Widget class.
private $client;
Inside the constructor of the class, initialize it as a Google_Client object. Then call the setAuthConfig() method and pass the location of the JSON file to it. The following code shows you how:
$this->client = new Google_Client(); $this->client->setAuthConfig(__DIR__ . '/MyCalendarApp.json');
Additionally, you must request for a specific OAuth 2.0 scope. For now, because we’re only interested in reading the contents of a calendar, request for a readonly scope.
$this->client->setScopes(
"https://www.googleapis.com/auth/calendar.events.readonly"
);
7. Reading Calendar Data
Using the generic Google API client, you must create a dedicated client for the Google Calendar service. So add the following code inside the widget() method of your class.
$calendarService = new Google_Service_Calendar($this->client);
At this point, you need to specify which public Google Calendar you want to use. For now, let’s use the USA holidays calendar. So create a variable to hold its ID.
$myCalendarID = "en.usa#[email protected]";
Feel free to visit Google Calendar to find other interesting public calendars. You can get the ID of any such calendar by opening its settings page.
To fetch a list of events from the calendar you’ve chosen, you can simply call the listEvents() method offered by the calendar service client. The method expects you to pass the ID of the calendar as its first argument.
By default, the method returns all the events present in the calendar. To make sure that it returns only upcoming events, you can use the timeMin option and pass the current date to it, formatted as an RFC3339 timestamp. Optionally, you can use the maxResults option to limit the number of results returned.
The following code shows you how to fetch four upcoming events:
$events = $calendarService->events
->listEvents($myCalendarID, array(
'timeMin' => date(DATE_RFC3339),
'maxResults' => 4)
)->getItems();
Each event has a summary, which is nothing but the title of the event, a description, a start date and time, an end date and time, a location, and several other such useful properties. To keep things simple, in this tutorial, we’ll be working only with the summary and the start date of each event.
Anything you echo from the widget() method will be automatically rendered by the widget. So all you need to do now is echo the two properties for each event. The following code shows you:
foreach ($events as $e) {
echo
"<p>" .
$e->start->date .
"<br/>" .
$e->getSummary() .
"</p>";
}
If you refresh your WordPress blog now, you should be able to see events from the calendar in the sidebar.
Conclusion
You now know how to use the Google Calendar API to create a calendar plugin for WordPress. Feel free to use the plugin to share your business or personal schedule with your users, inform them about upcoming offers and discounts, and even attract them to the local meetups you organize.
To learn more about the Google Calendar API, refer to the official documentation.