Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Note: As of Nov. 17, 2014, the 7.x-1.x and 6.x-1.x releases of Agenda stopped working because Google dropped support for version 2 of their Calendar API, which those modules were using. Use the 7.x-2.x and 6.x-2.x releases instead. See the README's in the module for installation instructions, many of which are inconsistent with this page. As a result, portions of the remainder of this page are outdated and should be updated to reflect that (or the pieces of this that are still accurate should be moved into the README of the module).
Agenda Module Documentation for both the Drupal 6 and Drupal 7 versions
1. Overview: The Agenda module allows you to display a list of upcoming events from Google Calendar as a block on your website.
The events are automatically downloaded and cached from the Calendar IDs specified in the Agenda administration page. Unlimited calendars can be added, and the colors for each calendar can be specified in the CSS file.
The output is fully theme able, and uses jQuery for dynamic effects such as rounded corners, and click-toggling extra information.
2. Preparation/dependencies
In Drupal 7 you need to have the Block module (part of Core) enabled, so do that first, if necessary.
For both Drupal 6 & 7 take note of the note on the drupal.org/project/agenda page about the date API and Date Timezone module. It reads, Note: If your dates are displaying a day off, you might be suffering the effects of Daylight Savings Time. Try installing and enabling the Date API and Date Timezone modules, then Daylight Saving Times are handled correctly. Apparently there is no longer a separate Date Timezone module. Perhaps it has been wrapped into the Date module. Anyway, make sure you have the Date Module installed and then enable Date and Date API. You won't need the other calendar functions for Agenda.
3. Installation:
Install the Agenda module like any other module. Place it the /sites/all/modules folder and then enable it.
4. Agenda Block creation and configuration/editing
A. Menu links: for Drupal 6 /admin/settings/agenda
for Drupal 7 /admin/config/services/agenda
B. Installation test: Before you create your own module you may want to look at the Example agenda block to test your Agenda installation. Click on configure and review at the various settings. Then click on the back page arrow and select debug next to the example agenda-block. You should see a display headed Test Settings with a long list of settings, returned and parsed events, and a list of events to be displayed. You will use this debug setting to test the blocks you create.
C. How to create a new block from your calendar(s)
To create a new block navigate to the proper menu link above, click on create a new block, and then fill in the required items. Notice that when you hover your cursor over the label for each item a short explanation pops up. Some more details are given below
A good working procedure would be to give your block a title in the first entry, then leave all the default entries as if for the time being, and drop down to the GOOGLE CALENDAR IDS entry. Once you have the link to the desired calendar(s) working and block displaying on your site where you want it, you can come back and configure the other entries to your liking. Most of the entries are self explanatory but note the following:
-AGENDA START: You can enter any string of letters that the php function strtotime can parse. The most commonly used are: [do not include " marks]
"yesterday" This sets the start time as 00:00:00 yesterday, the very start of the yesterday, so all of yesterday's events will be fetched and displayed.
"-1 day" This goes back 24 hours from the current time. So events within the last 24 hours will be fetched and displayed.
"today" This sets the start time as 00:00:00 the very start of the current day. All the events of today will be fetched and displayed.
"now" This sets the start time as the current time and all the events that have not yet started will be displayed.
Note: There are two current issues relative to AGENDA START listed on the Agenda project page. See the footnote at the bottom of this document.
-FORMAT OF DATES DISPLAYED: (Drupal 6 only) You can choose small, medium, large, or custom. If you choose custom, you must define that custom setting in the next boxes. The small, medium, and large date/time formats are set by the site administrator at admin/settings/date-time/formats.
-CUSTOM DATE FORMATTING/DATE FORMATTING:
For Drupal 6 if you entered custom for the date formatting you must enter the date formatting here.
For Drupal 7 this is a required field, so enter date formatting here.
The example "l, F js" returns a date formatted like the Monday, February 22nd. If you wanted to include
the year you would make it "l, F, js, Y" You can find all the formatting options by web searching for php date() function.
-FORMAT OF THE TIMES DISPLAYED/TIME FORMATTING: The example block entry of "h:ia" returns a time formatting like 9:33am. Again you can find the various time formats by web searching for php date() function.
-CALENDAR LINK TEXT: This is explained below, after the DISPLAYED FIELDS explanation.
-AMOUNT OF TIME TO CACHE EVENT DATA: Your setting here depends on how frequently new events are entered into the calendar. The default setting of 3600 seconds equals an hour. You might want set this shorter will testing your blocks.
-DISPLAY FIELDS: The module is set up to list only the event titles. To see more detail on any event in the list, you can click on an event title to bring up more information. The DISPLAY FIELDS setting here sets what information is displayed when clicking on an event title in the Agenda list. A complete list of possibilities can be found by clicking debug on the Example Agenda block and looking at a parsed event. The most useful options are: calendar, where, description, start date, start time, end date, end time, url, link, when. Enter in a common separated list the fields for the details you want to have available.
-HIDE LABELS: If you display fields in the previous item, you now have to decide whether the labels for that fields should also be displayed. Notice that you list the fields for which the labels should not appear.
-CALENDAR LINK TEXT: If you include link as one of the DISPLAY FIELDS, enter the text that will be displayed for the link to the Google Calendar.
-GOOGLE CALENDAR IDS: The Google Calendar ID field lets you fetch events from multiple calendars. Put each ID on a separate line. You can access add both private and public calendars although the procedure is slightly different.
To add a public calendar, the Calendar ID can be found by going to the Google calendar, selecting the down arrow next to the calendar name and selecting Calendar settings. The Calendar ID is then shown beside Calendar Address. This can be entered into the Google Calendar ID field.
To add a private calendar, the popup instruction says, "include the access token after the email with a forward slash." Here's an explanation: Navigate to calendar settings as above. Find the orange xml button next to Private Address. Right click on that xml button and select copy link location. Paste it into the Google Calendar IDS field box on your block configuration page. This will be a long url. Something like this [abbreviated on the left]
.../feeds/name%40googlemail.com/private-d258678ggt8b5cef869aa0c10fc044ad/basic
Notice the private- and a long hexadecimal number. That is the access token. Trim the ends and change the %40 to @ It will look similar this: name@googlemail.com/private-d258678ggt8b5cef869aa0c10fc044ad So you will have the email address, a forward slash and the access token.
-TIMEZONE: As the pop up says, enter the timezone identifier to be used for this calendar, as described in the PHP manual. Find at php.net/timezones
So now save the settings and the next step will be testing the calendar
5. Testing/debugging.
After you've saved the configuration, click on debug next to your new block. The debug link when creating or editing a block is very helpful to see whether the link(s) to a calendar(s) is/are working, what information is being retrieved, and what events will displayed in the block.
6. Assign the block to a page and region for display.
A. Menu links: Drupal 6 /admin/build/block/config
Drupal 7 /admin/structure/block
B. Step one: Block placement
For a new block, first find it in the disabled block list and and assign it to a region using the drop down list. Click on Save Blocks to save the block placement.
C. Step two: Configuring/editing the block display options
Select configure next to the block so you can edit the title and visibility settings for your block(s). For the visibility settings you can set user, role, and page specific settings. Make your selections and click on Save Block
7. Test your calendar block.
Using a role that has visibility rights to the block access the page where your block is to appear You may have to clear your browser and site caches before your block will appear. If you added multiple calendars, the events will be displayed with different colors, depending on the source calendar. Clicking on an event will display more information about the event using some jQuery. What will be seen depends on the DISPLAY FIELDS setting (see above). If you shortened the cache time for testing, reset it to an appropriate length of time.
8. A possible issue that needs exploration and testing.
Since the content of the calendar is dynamic, there may be issues with Agenda not updating properly due to browser and site caching. There is a setting on the module itself waits until rechecking for changes to the calendar. The use of the Ajax Blocks module or the cache exclude module may resolve these issues. The Ajax Blocks module has been tested with a Drupal 6 site that has an Agenda block on the front page and that seems to work well.
9. Appearance
Many thanks to Danny who gave permission to use material from his Agenda tutorial http://www.webomelette.com/agenda-module-google-calendar-in-drupal. In that tutorial he gives some suggestions about changing the appearance of the block. None of that material will be duplicated here.
However, if you change/edit the agenda.css or agenda-block.tpl.php files, updating to a later version of the agenda module will overwrite your changes. There is a way around that. See 9-A, B & C below below.
9-A. For the css changes, create a styles folder in your theme directory, and put your edited agenda.css file there, giving it agenda.css as a name. You can leave the original unedited agenda.css file in the agenda module folder. In the .info file for your theme insert the following line: stylesheets[all][] = styles/agenda.css
9-B. For the block template changes, in your theme directory there is a folder called templates. If one does not exist, create one. In that folder place your edited agenda-block.tpl.php file. You can leave the original unedited version in the agenda module directory. This will change all of your blocks. Rather than having a changed tpl file apply to all your blocks, you can assign an edited block.tpl file to a particular block. See the following: https://drupal.org/node/1089656
9-C. Suggestions 9-A & 9-B work best in connection with creating/using a sub-theme. Place the templates and styles folders under that sub-theme. This will preserve any changes, should the theme itself be updated. See: https://drupal.org/node/225125
10. Including the event start time and end time with the event title in the visible listing.
If you want the start time and end time to appear along with the event title in the visible list like this: "Event 6:00am-7:00am", you can accomplish that with a small code change.
In the agenda-block.tpl.php file find the following line:
echo $event['title'];
Replace it with the following three lines of code:
$trimstime = ltrim($event['start time'], "0");
$trimetime = ltrim($event['end time'], "0");
echo $event['title']." ".$trimstime."-".$trimetime;
--------------------------------------------------------------------------------
Footnote: There are two current issues relative to AGENDA START listed on the Agenda project page.
-The one concerns the fact that the module will sometimes display items before the start time. This will be noticeable with the "now" setting and the "-1 day" setting. The issue author has suggested a change in the agenda.module code to filter out all events before the AGENDA START setting. That issue along with the suggested code change is at https://drupal.org/node/2138529 A patch with the change is also listed there.
-The other concerns what events are fetched from the Google Calendar(s). Since the code currently uses only the day part of the AGENDA START time setting, events may be fetched before the start time setting. Again this is most noticeable with the "now" and "-1 day" settings. Even if those events are filtered out, this can lead to a large reduction between MAXIMUM NUMBER OF EVENTS TO FETCH setting and the actual number displayed. The issue author has suggested a change in the agenda.module code. Issue is explained in detail in comment #3 under that and the author of the comment has suggested a better code change. The issue along with the suggested code change is at https://drupal.org/node/1336392 A patch with the change is also listed there.
