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.

3,253 Responses

  1. Hi! I really like your plugin, great work! Planning on using it soon… Here’s some suggestions for future development that I would really like to see:

    - Multilingual support, meaning that all the strings like “Starts:” and “Ends:” go into language files.

    - Related to multilingual support again, since the calendar data is entered in Google Calendar and is not localized (unless I missed something), to add the ability to assign a language to a calendar widget or to a calendar added to a post.

    For example, for now we can assign the IDs of the calendar that we want the widget to display, and that alone allows us to select a Google calendar in a particular language. You could also add an optional language field to enter for example, “fr” for french or “ru” for russian, in the widget parameters, to make sure that those calendars are displayed only when that language is active (I wouldn’t want to see the russian calendar while navigating in french). Of course I’d have to add one calendar widget for each language but that’s not much work. Maybe there’s a more simple solution?

    Thanks again,
    Francis

    Reply
  2. Hi Ross, thanks for replying. :-)

    Using get_bloginfo(‘language’) gives you the current language of the page, regardless if there’s a multilingual plugin installed or not. You’ll get for example en-US for english or fr-FR for french.

    Now, in the parameters of a calendar feed in “Add a New Feed”, you could add a simple text field allowing the user to enter fr-FR if he wanted to assign that language to that feed, or en-US, etc.

    So if there’s a language code entered in that field, then you check if it’s the current language and if it is, the calendar widget is displayed. If there are no language entered then the calendar widget is displayed no matter what.

    Another way to get there would be to add that language parameter field inside the widget parameters instead of the calendar feed parameters.

    Thanks again!
    Francis

    Reply
  3. Curious question. I have activated and added a feed, however it is not being parsed and I am wondering if it has to do with the email itself having a period “.” inside it thus making the link look like such:

    `http://www.google.com/calendar/feeds/cte.leeu@gmail.com/public/full`

    Reply
  4. Trying to use your plugin to take feeds from a google calender which is not the primary one, but very much a public one here : http://www.google.com/calendar/feeds/j4f78pjkbldqr92qjraj12hvh4%40group.calendar.google.com/public/basic
    However, your plugin (0.4.1 release) states that this is not a valid feed and does not work with it.
    Any clues ? I’ve not done anything but unpacked it , activated it and attempted to use the above url as a feed with no joy…

    Reply
  5. Hi Ross
    I’ve installed the pluggin to a site im developing for a pub, however last weeks events are still appearing on the calendar in the sidebar. Is there an option somewhere that removes events once they have passed?

    Reply
  6. Hi Ross, I love the widget. One question, Is is possible to display the month from Sunday-Saturday instead of Monday-Sunday?

    Reply
  7. Dear Ross,

    You are a most excelent guy for providing such excellent, timely and tolerant support for your plug-in!

    Thanks!

    Reply
  8. Is it possible to have all links in page list or widget list go to the week view of your calendar instead of to the individual events?

    Reply
  9. Hy Ross,

    i’ve installed your really well done calander plugin for a client of mine and got only one strange problem with the minicalendar: If you hover over a Day the details appear with a wrong End-Date (Day+1), but the table-cells are correctly colored!

    I can’t find the problem, do you have a hint for me? (Link of Website is client’s website).
    Yours, Bernhard

    Reply
  10. Hi Ross,

    Since upgrading to 0.4.1, in order to display 3 calendar events, I have to put 4, in the “max number of events to display” field.

    Any thoughts?

    Thanks!

    Reply
  11. Dear Ross,

    I am hoping the “All Day” option comes along soon. In the mean time is there a work around?

    You rock!

    Reply
  12. Hi Ross,

    I can only get monday-friday, presumably because my widget area isn’t wide enough. I can’t work out where I add code to make it thinner though? I’ve added the style sheet again, renamed it and faffed about with it, but I can’t manage to change the actual size of the box.

    Is this possible and I’m missing something really obvious, or not?!

    Thanks!

    Chris

    Reply
  13. Thank you for the amazing work you have done with this plugin, it is a great time saver.
    One question that has been nagging me that I feel ‘m missing something obvious.

    In the option to display the feed as a list, is it possible to link each listed event to a different WordPress page or each list item to link the same page? The “more” link just goes to the default Google display page that is rather boring. If I could either change the “More” link to go somewhere else, or link the title, it would solve a lot of problems.

    Am I missing the obvious on this one? Thank you for your help.

    Reply
  14. Hi Ross,

    Many thanks for your usefull plugin!

    It *seems* your plugin is feeding to death the WP’s options MySQL table with datas starting with ‘_transient_timeout_feed_%’ or ‘_transient_feed_mod_%’

    If so, how can I prevent your plugin to do it ?

    Reply
  15. Thanks Ross.
    Actually there are more than 5000 transients related entries in my database and still growing (I only have 3 Google feed URL and nothing else using RSS feeds).

    From WP Codex, Transient datas are supposed being deleted after a provided timeout. So there are 2 problems :
    - something create transient datas (I haven’t figured out if they are duplicates or not)
    - those transient datas aren’t cleaned

    I’ve contacted you because transient datas contain Google Calendar feed URL in them.

    I would like to help you in any manner (doing tests, debugging, … on my WP blog) in order not to clean manually the DB from time to time. Thanks again !

    Reply
  16. Hi Ross,

    Love this Plugin, I wanted to use it on a hyperlocal site I’ve been working with but thought I’d give it a test drive on mine first.

    This afternoon I’ve been playing round with it and tweaking the actual feed so it looks nice. I thought I’d drop a URL to the main website or review in the description as HTML. I could have sworn this worked to begin with but for some reason it’s not reading it as HTML now.

    Could you think of any reason why this might not work. I’m currently doing two feeds for the different widgets, one basic and one full.

    http://www.google.com/calendar/feeds/rebr8hlj2diit0qqp6lfsr00v0%40group.calendar.google.com/public/full

    http://www.google.com/calendar/feeds/rebr8hlj2diit0qqp6lfsr00v0%40group.calendar.google.com/public/basic

    The widget is being played with on the back end of my blog http://www.dandavies23.com/blowback

    Reply
  17. I have an issue where the plugin is showing that the end date is a day later than schedule for a series of all day events. This is using a widget displaying as a list.

    So if I have something scheduled from June 6 to June 12th, the plugin will show June 6 to June 13.

    Any ideas?

    Reply
  18. Hi again Ross,

    It’s slightly more complicated than I initially thought, I wanted to install the plugin on http://insidethem60.journallocal.co.uk/ which is a MU WP site. I don’t have access to the code and the admin is reluctant to do it, largely because

    “it could open up JL to cross-site scripting attacks.”

    Do you know when you’ll be bringing in an upgrade with the HTML parse option or do you have anything that may reassure him this a scripting attack is not a concern?

    Reply
  19. Thanks for this plug-in Ross, very useful.

    A suggestion for the todo is the possibility to add an offset. So it would be possible to show two grids (two following months) next to each other. I’ve hacked it together with jQuery now, but it might be useful for other users of the plug in.

    Keep up the good work.

    Reply

Leave a Reply