GCal Events

Last updated November 20, 2011. Created by Se7enLC on October 22, 2008.
Edited by KarenS, LeeHunter. Log in to edit this page.

GCal Events is a module which will display upcoming events in a block. The source for these events is a Google Calendar.

Who is this module for?

• If you want to simply and easily add a calendar to your Drupal site with minimal effort, this module is for you.
• If you already have a Google Calendar for your organization and want professional-looking integration

How does it work?
GCal Events subscribes to your Google Calendar's XML feed. It uses SimplePie to cache and parse the XML to get the title, location, date, time, and description from the event. These data fields are displayed in a Drupal block.

FAQs

• Why not use an iCal parser? Good question. iCal is a very complicated format which can handle a lot of complicated scheduling information (repeating/recurring events, etc). As popular as the iCal format is, there are very few iCal parsers available, and none that I could find that met the requirements for this module. That would make for an excellent extension to this module, however.
• Why do I need to download simplepie.inc? SimplePie is a separate project that GCal Events uses to cache and parse XML feeds. SimplePie is released under the BSD License, rather than the GNU Public License that Drupal is licensed with.

Features
Here are some of the interesting features built into GCal Events:

• Can read from public or private google calendar
• Multiple blocks can be set up, each configured independently.
• Date/Time display format can be configured
• Timezone can be configured (PHP 5.1 and higher)
• Display uses templates, so each item (title, location, date, description, url, etc) can be configured for each block. Very flexible and powerful!
• Customizable "footer" to include brief information about the calendar ("provided by so-and-so", "updated weekly", a link to the full calendar, ical feed link, etc)
• Customizable "no upcoming events" text to display when no events are coming up.
• Repeating and all-day events are handled
• "Today Only" option to show only events occurring on this calendar day.

Installation

1. untar into modules directory (sites/all/modules)
2. Download SimplePie (http://simplepie.org/)
3. Copy simplepie.inc into the modules/gcal_events directory
4. Create a cache directory that is writeable by the webserver (defaults to modules/gcal_events/cache)

Configuration

1. Enable the module in Drupal
2. Create an input filter to use for gcal_events (I recommend calling it gcal_events). You will most likely want this input filter to be accessible to anonymous users.
3. Make sure to select this new input filter in the gcal events module configuration.
4. In the module configuration, set the cache directory and number of blocks to display
5. In the block configuration screen, configure block 0. Get the Calendar ID from google calendar.
6. Still in the block configuration screen, set the block to an active region and save

You should now see a few upcoming events in the block you configured. You can tweak the title of the block and how the events are displayed in the configuration screens.

How to get Google Calendar ID and Private ID
(Note: As of gcal_events.module version 1.5, you can just copy and paste the XML address and the Calendar ID and Private ID will be parse out automatically) If you are testing out the module and need a calendar to try, I recommend a Google Calendar ID of usa__en@holiday.calendar.google.com. That is a public calendar of US Holidays. It is guaranteed to always have a few upcoming events and should work in all cases.

1. Log into your Google Calendar.
2. Click on the "Settings" tab.
3. Select "Calendars"
4. Click on the calendar you want to use.
5. In the section labeled "Calendar Address", you should see "Calendar ID". Copy and paste that ID. into the GCal Events configuration.

If you just fill in the Calendar ID, GCal Events will default to using your public calendar. Events marked as private will not show up. If you want to display your private
calendar (not advised):

1. Under the section marked "Private Address", click on XML
2. You will see a URL that looks something like this:

http://www.google.com/calendar/feeds/somename%40gmail.com/private-0562849527c0abe35379accccb4ecfd4/basic

3. For Private ID, you are looking for the section between "private-" and "/basic"

Template Customization
GCal Events was written to be a very flexible and customizable module. Rather than having people download the module and modify the code to meet their unique needs, I tried to write the module in a way that it can be configured to meet the majority of those needs.

Each Google Calendar XML feed contains events with the following fields:

• Title (#TITLE#)
• Location (#LOC#)
• Date (#DATE#)
• Time (#TIME#)
• URL (#URL#)
• Description (#DESC#)

In addition, GCal Events provides these modified fields for your use:

• URL-Encoded Location (#LOCURL#)

An event block uses templates to display these fields in the format you specify. The Event Template is the template that combines all the fields together. You can add html tags or linebreaks as needed between elements.

In addition to the Event Template, each field has a template of its own which specifies what should be done to that field before including it in the Event Template

• Title Template
• Description Template
• Date Template
• Time Template
• Location Template

Typically, you will want to keep the Events Template free of any customization that applies to a field individually, like a bold tag or linebreak tag. This is done so that if a field is missing from the XML feed, the extra linebreak will not be shown (for example, an all-day event will not have a time, so you do not want an extra blank line showing up for that).

Here are some example customizations:

• To get the title to be a link to the event in google calendar:

Title Template: <b><a href="#URL#">#TITLE#</A></b><br>

• To get the location to be a google map:

Location Template: <a href="http://maps.google.com/?q=#LOCURL#">#LOC#</A>

Time/Date Customization
Time and Date formats are very customizable. The default format for time/date display can be configured in the GCal Events administration page. Each block can also be configured to override that if you need a different display in a different block.

Timezone Configuration
On most systems, timezone configuration will not be needed. The "local time" according to the machine hosting your page will be what is used. If the machine is set up using UTC or a different timezone, you may need to select an alternate time zone to display the events correctly.

Feature Requests

• Configurable look-ahead time for events: Set a maximum time to look for events (next 30 days, next 5 days, etc). Current behavior is to look for ALL future events
• Current week/month/year only: Only display events from the current week, month, or year, rather than the next X events which might span a week/month/year border.
• php code: Allow a block of custom php to be executed for the block or for each event. This is a potentially risky feature, and unless a really good reason comes along, I see no reason to add it.

If you want/need one of these features or think of another feature you could use, please let me know! It's possible that it is already possible and just needs to be configured. If not, there's a possibility that if you could benefit from a new feature, somebody else could as well, and that would make a worthwhile addition.

More Information

• README

Authors

• Originally written by Jeff Simpson
• Adapted from code written by James Cridland

Please post issues/suggestions/etc on the GCal Events Project Page. Comments posted here might go months before anybody sees them.