Google Calendar Events

This is a WordPress plugin, which parses Google Calendar feeds and displays the events as a calendar grid or list on a page, post or widget. Events from multiple feeds can be displayed on one grid or list. You can specify how many events to retrieve, whether to retrieve past events and how long to cache the feed for, amongst other things. Grids can have AJAX functionality, which allows you to change the month, if required.

The calendar grid markup is generated using a modified version of the PHP Calendar script (2.3) by Keith Devens. As of version 0.2, tooltips are created using the jQuery tooltip plugin, qTip.

Don’t hesitate to let me know if you have any questions, problems, feedback etc. Leave a comment at the bottom of the page or contact me.


Jump to:


Demo

Visit the demo page to see what the plugin can do.


Download

The current version is 0.7.2

You can download Google Calendar Events from the WordPress plugin directory page.


Installation

Either use the automatic installer from within your WordPress admin, or follow the below steps:

  • Download google-calendar-events.zip from the plugin repository
  • Extract the file
  • Copy the google-calendar-events directory to your WordPress plugins directory (probably wp-content/plugins)
  • Login to your WordPress admin, navigate to the Plugins section and activate Google Calendar Events
  • You should now see a new Google Calendar Events settings page under the Settings tab

Adding a Feed

Go to the Google Calendar Events settings page and click the Add Feed button. Here’s an explanation of the various fields:

  • Feed ID
    This is automatically assigned, it’s just a unique identifier.
  • Feed Title
    This can be whatever you like. Try to use something descriptive so that it will be easy to remember which feed is which (e.g. ‘Upcoming Club Events’ rather than ‘Feed 1′).
  • Feed URL
    This is the URLto the Google Calendar feed. It should be something like this:http://www.google.com/calendar/feeds/your-email@gmail.com/public/fullThe end of the URL may have /basic or /fullon the end, both should work ok.If you are using your own feed, you can find the URL by logging into Google Calendar then clicking on the calendar settings. In the Calendar Address section you should see an orange XML button, click on it to see your feed URL. Copy and paste the URL into the Feed URL field.
  • Retrieve events from
    The time at which to start retrieving events. Select one of the options from the drop-down box, and then specify an additional offset for the start time / date you require. The offset should be given in seconds (3600 seconds = 1 hour, 86400 seconds = 1 day), and can be negative.If you are using the ‘Specific date / time’ option, enter the UNIX timestamp for the date / time into the textbox. You can generate UNIX timestamps here.Take a look at this post for a few examples of how to use this option.
  • Retrieve events until
    The time at which to stop retrieving events.The instructions for the ‘Retrieve events from’ option (above) also apply here.
  • Maximum number of events to retrieve
    The maximum number of events to retrieve from the calendar feed. Due to caching and timezone issues, it is a good idea to set this to a higher number than you actually want to display. 5 to 10 higher should be fine in most cases. You can specify the exact number to display in the widget options or shortcode parameters.
  • Date format
    A PHP date format string. Leave this empty to just use the default for your blog (in Settings > General). Stick to just day / week / year formatting here, leave hours / minutes / seconds for the time format (below).
  • Time format
    A PHP date format string. Leave this empty to just use the default for your blog (in Settings > General).
  • Timezone adjustment
    If you are having problems with dates and times being shown incorrectly for your timezone, select your required timezone from the drop-down box.
  • Cache duration
    This is the length of time to keep the feed cached, in seconds (43200 seconds = 12 hours). You might want to reduce this value if your calendar updates very often but avoid setting it really low or page load times and calls to Google’s servers will be increased. If you want to update the feed cache ‘right now’ to check any events you have added to your Google Calendar, set this to 0, then refresh any page with the calendar on it. You should then set this back to a higher number.
  • Show multiple day events on each day?
    If checked, events that span multiple days will be shown on each day that they span. If unchecked, multi-day events will only be shown on their first day.

Display options

To control the information that is displayed for each event in the grid tooltip or list, you can use either the simple display options, or the event display builder. The event display builder is much more flexible than the simple display options.

The simple display options are described below. There is a separate, in-depth guide to the event display builder.

Simple Display Options

  • Display start time / date?
    Select how to display the start time and date for events from the drop-down box. You can also enter some text to be displayed before the start time / date in the textbox
  • Display end time / date?
    Same applies here.
  • Separator text / characters
    If you have chosen to display the time and date for either of the above two settings, you can specify the text / characters to separate the time and date here (include spaces).
  • Display location?
    If checked, the location of events will be displayed (if a location was set when the event was created). You can also enter some text to be displayed before the location in the textbox.
  • Display description?
    Same as the location, but you can also specify a maximum word count for the description text. This can prevent the tooltips / lists becoming very long if your events have lengthy descriptions.
  • Display link to event?
    If checked, a link will be displayed for each event, which links to the Google Calendar page for that event. You can also specify whether these links will open in a new window, and the link text to be displayed.

When you’re done, click the Add Feed button. You will be redirected back to the main plugin settings page and you should see your feed listed in the current feeds section.

Please note that Google Calendar feeds that you add should have public sharing enabled and have the ‘Share only my free/busy information (Hide details)’ checkbox unchecked (These settings are under ‘Share this Calendar’ in the Settings of your Google Calendar admin).


Event Display Builder Guide

The event display builder requires quite a lot of documentation, so has a page to itself! Please take a look at the event display builder guide.


Editing / Deleting Feeds

On the main plugin settings page, you should see Edit and Delete links for each feed you have added.

The Edit Feed screen is very similar to the Add Feed screen so should be fairly self explanatory by now.

On the Delete Feed screen, check that the feed displayed is the one you wish to delete, then click the Delete Feed button. Make sure that you remove or adjust any widgets or shortcodes etc. that used the feed you have just deleted or you may get errors.


Adding a Widget

You need to have added a feed before you can add a widget, see above for how to do that if you’re not sure. Also, your theme must be widget enabled. If it isn’t, try using one of the other methods explained below.

Once you have added a feed, go to the Widgets page of your WordPress admin (under Appearance) and do the following:

  • Drag the Google Calendar Events widget from the Available Widgets box into one of the widget areas on the right of the screen.
  • Click on the arrow on the right of the widget, you should see some options.
  • Enter the feeds IDs of the feeds you want to display in this widget as a comma separated list (e.g. 1, 2, 4). If you want to display all the feeds you have added, leave this blank.
  • Choose how to display the events from the drop-down-box.
  • Enter the number of events that you want to display in this widget (you can’t display more than the number you specified in the ‘Maximum number of events to display’ option in the feed settings). Enter 0 to display all events that were retrieved.
  • Choose whether you want events to be displayed in ascending or descending order. This only applies to lists.
  • If you want to display a title on the top of the tooltip / each list item, tick the checkbox and enter your desired title text in the text field (can be empty).
  • Click the Save button.

Adding to a Post or Page

To add a calendar grid or list to a post of page, you can use the following shortcode:

[google-calendar-events]

It takes up to four different parameters:

  • id – The IDs of the feeds you want to display as a comma separated list (all feeds will be displayed if this is omitted).
  • type – Should be one of the following (defaults to gridif parameter is omitted):
    • list – Events displayed in a list
    • list-grouped – Events displayed in a list, grouped by date
    • grid – Events displayed in a calendar grid for the current month
    • ajax – Events displayed in a calendar grid, with the ability to change months via AJAX
  • title – Title text to be displayed on the top of the tooltip / list items (no title is shown if parameter is omitted).
  • max – The maximum number of events to display (again, you can’t display more than the number you specified in the ‘Maximum number of events to display’ option in the feed settings). All events retrieved will be displayed if set to 0, or if this parameter is omitted.
  • order – The order of events. This only applies to lists. Should be asc or desc (defaults to asc if this parameter is omitted).

So, for example, to display 10 events from feeds 1 and 3 in a AJAX enabled calendar grid with the tooltip title ‘Events on’, use the following:

[google-calendar-events id="1, 3" type="ajax" title="Events on" max="10"]

You can also use the do_shortcode() function to add a grid or list anywhere in a theme / template, like this:

<?php echo do_shortcode( '[google-calendar-events id="1, 3" type="ajax" title="Events on" max="10"]' ); ?>

General Options

These are the options on the main plugin screen.

  • Custom stylesheet URL
    If you want to make changes to the default CSS styles, create a new stylesheet on your server (not in the google-calendar-events directory) and enter its URL into this textbox. The default stylesheet will be overwritten each time the plugin updates, so beware of editing it directly, you will lose your changes.
  • Add JavaScript to footer?
    If the AJAX functionality, or the tooltips don’t appear to work for your site, try ticking this checbox.
  • Loading text
    Enter the text to display when the calendar is loading during an AJAX request.
  • Error message
    Enter an error message to display to non-admin users if events cannot be displayed for any reason. Logged-in admin users will see different error messages indicating the cause of the error.
  • Optimise event retrieval?
    If enabled, the plugin will use an experimental parameter of the Google Data API, called fields. This feature can improve performance significantly as it allows the plugin to request only the information it requires. This means that there is less feed data to transfer and process. It is highly recommended that you leave this option enabled, however, as this is an experimental feature, Google could potentially remove or change it at any time.
  • Use old styles?
    In version 0.7, some changes were made to the default CSS stylesheet. Enabling this option will add another stylesheet that includes much of the stuff that was removed / changed. You should consider updating your custom stylesheet so that you don’t need this enabled. This option will be removed in a future version.

Notes for Google Apps Calendar Users

If you are using a feed from a Google Apps Calendar and are having issues getting things up and running, please take a look at the notes for Google Apps Calendar Users.


AJAX grids

A few things to remember about AJAX grids. This applies to both widgets and full page grids.

  • To have the ability to change month on a grid, you must use the AJAX versions of the grids. See the above sections for how to do this.
  • To change the month, click on the arrows that appear on either side of the grid title.
  • The arrows will only appear if there are more events to show in that direction. For example, if the grid is showing July and there are no events in August or beyond then the next month arrow will not show.
  • Each time you click on one of the arrows, the information is requested from the server, so will take a small amount of time to appear (generally a couple of seconds).

Frequently Asked Questions

For answers to commonly asked questions, please visit the FAQ page.

If the FAQ don’t help, please ask in the comments below, or send me an email.


Things to Note

  • The calendar grid uses the WordPress ‘Week starts on’ setting to determine on which day the grid will start. You can change this in Settings > General.
  • Only a very basic CSS stylesheet is included. The intention is that you will adjust the stylesheet to fit your theme.
  • Styles and JavaScript are added by wp_head() or wp_footer() (if the relevant option is enabled) so ensure that you theme uses these functions or you will need to add the CSS and JavaScript files manually.
  • The plugin is still very much under development so there may be rough edges. I would appreciate any feedback, including bug reports and requests for additional features. Leave a comment below or contact me. Thanks!

To Do

Things I hope to implement / improve at some point:

  • Allow event information to be displayed within calendar grid cells (not just in the tooltip)
  • Different groupings for the grouped list (week, month, year etc)
  • Better handling of feeds that contain only free / busy information
  • Only load JavaScript when needed on the page
  • Allow a month other than “this” month to be displayed initially for calendar grids (first month that has events?)
  • Convert feeds to a custom post type

Any other suggestions?

Donations

Several people have asked about making a donation to the continued development and support of the plugin, so I’ve finally got around to sorting it out! Any donations will go towards website hosting costs and stuff like that.

Donations are much appreciated, but please do not feel in any way obligated to donate! I develop and support the plugin because I enjoy doing so, not for any financial gain.

Leave a Reply