Calendar Plugin

Name Calendar Plugin
Vendor Atlassian Software Systems (Website)
Authors David Peterson, Mike Cannon-Brookes, Jens Schumacher, Jeremy Higgs, Dan Hardiker, James Matheson, Swee Wan Tan, Richard Wallace
Homepage http://confluence.atlassian.com/display/CONFEXT/Calendar+Plugin
Issue Management http://developer.atlassian.com/jira/browse/CAL
Categories Content Macros
Version 2.7.1
Availability Confluence v2.8.1 to v2.9-m2-r2
State Stable
License Freeware / Open Source (BSD)
Price Free
Release Docs http://confluence.atlassian.com/display/CONFEXT/Calendar+Plugin
Java API Docs n/a
Download Source http://svn.atlassian.com/svn/public/contrib/confluence/calendar-plugin/tags/calendar-plugin-2.7.1/
Download JAR calendar-plugin-2.7.1.jar
This plugin now accessible through the Confluence Repository Client.

Description


This plug-in puts a dynamically updated calendar into any page. The calendar stores its data in iCal format and allows incoming and outgoing calendar subscription.
The plugin offers day, week and month views. You can have multiple calendars per page. And your items can link to other pages for elaborating details.

Possible Bug
Users have reported that some accounts cannot see scheduled events. We recommend that you notify your users about the risk until we can fully re-test the plugin.



Downloading & Installing

Due to changes in Daylight Savings Time laws in the US, it is important to update your JDK if you are having issues with dates after March 11, 2007. See the following page for details:
http://java.sun.com/javase/tzupdater_README.html
Due to changes in Confluence, there are separate versions for Confluence 1.4.4, 2.0 and 2.1. Uploading the plugin is only supported from plugin version 2.3 onwards.

Screenshots

(view as slideshow)
       
  The vacation calendar.   Adding a multi-day all-day event.   An event in the Brisbane timezone.  
 
       
  Add events by clicking the icon.   Adding an event in the Bangkok timezone.    
 
       
  Adding a calendar - step 1      
 

Macros

{calendar:id=mycal|title=My Calendar}

Details: Outputs an editable dynamic calendar.
Parameters:

Name Required Description
id The unique identifier that identifies this calendar. Must be unique per page. May only contain numbers and letters of the alphabet.
title The human-friendly title for the default sub-calendar. Not necessarily unique.
defaultView Allows the default view of the calendar to be specified. May be 'event', 'day', 'week' or 'month' (the default)
firstDay Allows the specification of the first day of the week. May be any day of the week. Defaults to Monday.

{calendar-events:page=Page Name|calendarId=mycal|}

Details: Outputs the events for the named calendar.
Parameters: PLEASE COMPLETE MACRO DESCRIPTION

Name Required Description
page The name of the page containing the calendar. May be just the page name ('My Page') for local pages, or prefixed with the space key ('SPACE:My Page') for those elsewhere.
calendarId The ID of the calendar to display events for.

Examples

Creating the basic calendar

Creating a calendar is a two-stage process. Firstly, you have to define where the calendar will appear on the page. Edit a page in Wiki Markup mode:

Below is my vacation calendar.
{calendar:id=vacation|title=My Vacation}

By specifying the title, a new calendar called 'My Vaction' will automatically be created for you. It should look something like this:

You can add events to this immediately.

Adding Events

To add a new event, hover your mouse over a day on the main calendar display and click the 'add event' icon which appears:

Next, a panel asking which calendar you want to add to will appear:

Select 'My Vacaction' and click next. Enter the details for the event:

Click 'Add' to finish the job.

Adding a new calendar

Alternately, you might want to add a new calendar, either one allowing events to be added via Confluence, or one which subscribes to an iCal file elsewhere on the Internet.

Firstly, click the 'Add a calendar link'. If more than one type of calendar is available, you will have to select the calendar type:

Then, enter the calendar details:

The example above is subscribing to the 'Australian Holidays' calendar. You can subscribe to it yourself by entering the following URL as the subscription location:

http://icalx.com/public/rohanl/Australian32Holidays.ics

If you want to be able to add events through Confluence, set the location to 'Local'.

Timezones

With version 2.1.10 of the plugin, you can now specify both specific event timezones as well as the display timezone for the main calendar.

Adding events in different timezones

Setting the timezone for an event is simple - just change the the option below the event time. Note that all-day events do not have a timezone - they apply to the whole day on the specified date, regardless of the timezone. An example is below:

Viewing the main calendar in a different timezone

You can change what timezone you view calendars in. Note that you must be logged in for this to work, and the setting will apply to all calendars on the site. You can change the display timezone at any time.

To do so, simply click on the name of the current timezone in the top-left of the calendar display:

You will then be asked to select a new timezone. Choose the one you want and click 'Save'. You will be returned to the page you came from.

Note: In Confluence 2.3+, this now uses the standard user-set timezone, available in the user's preferences.

Publicly Available Calendars

There are numerous public calendars for things like holidays, regional events, etc. One of the best repositories can be found at http://icalshare.com/.

Custom Themes

If you are using a custom theme, you need to ensure that some javascripts are included in your theme (or create a user macro to get them included on your page). This is also important to ensure that other Confluence features like labels are correctly supported.

The scripts are prototype.js and effects.js - both of which can be obtained from http://script.aculo.us

These scripts are usually included with Confluence 2.x standard themes.

Internationalization

The plugin is mostly internationalized. 95% of the text has been put into a properties file (CalendarMacro.properties. Other languages can be added by creating modified versions of this file and saving them with the appropriate language code (eg. CalendarMacro_de.properties, etc.)

How this file is linked into Confluence depends on the version of Confluence you are using.

Confluence 2.3+

The files must now be loaded into the plugin to work, although alternately a separate plugin can be created for additional language files if this works out to be simpler. In the meantime, the German translation has been added to Calendar 2.3. Please feel free to supply translations into other languages.

  • In Confluence 2.3 (using Calendar 2.3+), the locale will be that specified by the user themselves, or the server default if they do not have one. If a translation is not available for the current locale, it will display the default English translation.

Also, feel free to contribute any translations you produce here and they will be added to future versions of the plugin. Contributions so far are listed here:

  Name Size Creator (Last Modifier) Creation Date Last Mod Date Comment  
Text File CalendarMacro_de.properties 5 kb MartinMitry Feb 21, 2007 Feb 21, 2007 German localization

User contributed information

Performance Advisory
This is one of the best plugins for Confluence, however it's also one of the most system and database intensive and is susceptible to users inadvertently creating calendar pages that can consume massive amounts of system resources while rendering the page.

Open Issues

Atlassian Developer Network JIRA (25 issues)
T Key Summary Reporter Status
Bug CAL-265 "Already connected" error when supplying username and password for HTTP iCal subscription Alastair Burr Open
New Feature CAL-264 Add a property to setup the starting date of the calendar Rodolfo Romero Open
Bug CAL-263 Calendar extractor causes Confluence indexing to stall completely due to what seems like an infinite loop inside ical-4j Dave Loeng Open
Bug CAL-262 Colours on events in the calendar are only displayed in "weekly" view and not the "monthly" view wiki-support@cisco.com Open
New Feature CAL-261 Year view for Calendar Abhishek P C Open
Improvement CAL-258 Adjust {calendar-events} to render the title as a link pointing to the link of the calender entry Marco Beelen (IPROFS) Open
Improvement CAL-257 If a user specifies an alias or the name of an internal page for a link, the alias or page name should be used by calendar-events Michael Spoonauer Open
Improvement CAL-256 Float 'Event Details' to always appear on the screen Kyle Hickson Open
Improvement CAL-255 Allow users to specify a page that doesn't exist yet for a link, just like Confluence does Michael Spoonauer Open
Bug CAL-254 Receive NullPointerException when attempting to specify an internal page for a link Michael Spoonauer Open
Bug CAL-253 Indexing Error Barry Pape Open
New Feature CAL-252 Add a parameter to {calendar-events} to display events of a day/week/month etc. Thomas Lohschmidt Open
Bug CAL-251 Recurring events in iCal files cause long page render times Ben Batt Open
Bug CAL-249 Is Calendar 2.6.1 compatible with Confluence 2.7.2? Roy Hartono Open
Bug CAL-247 Calendar plugin doesn't check whether it's referring to itself James Fleming Open
Bug CAL-246 Calendar db connections leaking - close/release ? Ivan Benko Open
Bug CAL-244 DTSTAMP in ics file causes server error on loading calendar Robert Cole Open
Bug CAL-243 java.lang.NoSuchMethodError on lucene when trying to display a calandar Kev D'Arcy Open
Bug CAL-242 "You must specify a search term" error upon invite Gurleen Anand Open
Task CAL-241 Retest Calendar plugin on Confluence 2.7 David Soul Open
Bug CAL-240 Calendar events appear for some users but are invisible to others David Soul Open
Bug CAL-239 event times are wrong on remote iCal subscription from GMT+5:30 Jason Stewart Open
Bug CAL-238 Subscribe to calendar generates faulty URL James Hines Reopened
New Feature CAL-237 Calendar-Events Macro Should Allow Limit Output to Titles John Martin Open
Bug CAL-236 {calendar-events} Multiple sub-calendars with large numbers of events will prevent proper listing John Martin Open

Release History

Version Date State License Price
Show description 2.7.1 (#26) 20 Jun 2008 Stable Freeware / Open Source (BSD) Free

Release Notes

Disabled the Calendar extractor.

Contributors

  • Richard Wallace — Developer

Show description 2.7 (#25) 06 Jun 2008 Stable Freeware / Open Source (BSD) Free

Release Notes

Confluence 2.8 compatibility fix.

Contributors

  • Richard Wallace — Developer

Show description 2.6.1 (#24) 10 Jan 2008 Stable Freeware / Open Source (BSD) Free

Release Notes

This is a bugfix release for users that encountered problems when calendars had the same ID on different pages clobbering each other ([ CAL-219 | http://developer.atlassian.com/jira/browse/CAL-219 ]).

Contributors

  • Richard Wallace — Developer

Show description 2.6 (#23) 18 Dec 2007 Stable Freeware / Open Source (BSD) Free

Release Notes

Summary

This release fixes bugs related to caching of remote calendars and calendars displayed from attachments and compatability with Confluence 2.7.

Issues Resolved

Atlassian Developer Network JIRA (6 issues)
T Key Pr Summary Updated Reporter Status
Bug CAL-207 Major Caching issue with calendars based on attachments Dec 18, 2007 David Dembo Resolved
Bug CAL-204 Major Unable to read the calendar ERROR - Calendar Plugin v 2.5 Jun 16, 2008 Tony CheahTongNyee Resolved
Bug CAL-216 Major Unable to install calendar plugin Dec 18, 2007 Tony Inglima Closed
Bug CAL-210 Major Source not compatible with Confluence 2.7 Dec 05, 2007 David Chui Resolved
Task CAL-209 Major ContentPermission import needs changing from core package to security for Confluence > 2.3 compatibility Dec 05, 2007 David Taylor Resolved
New Feature CAL-234 Minor Can the Confluence plug-in work with JIRA calendar plug-in? Feb 13, 2008 Royce Wong Closed

Contributors

  • Richard Wallace — Developer

Show description 2.5 (#22) 15 Nov 2007 Stable Freeware / Open Source (BSD) Free

Release Notes

Summary

This release fixes a number of bugs and introduces some new functionality. This release is NOT compatible with Confluence 2.6.0 due to problems with the CSS stylesheet handling in Confluence 2.6.0. This version is compatible with 2.6.1.

Issues Resolved

Atlassian Developer Network JIRA (17 issues)
T Key Pr Summary Updated Reporter Status
Bug CAL-158 Minor Views not resolving embedded variables Oct 15, 2007 Brian Sanders Resolved
Bug CAL-163 Minor Deletion all day event results in error Oct 25, 2007 Jason Perry Closed
Bug CAL-155 Major {calendar} Plugin Time Zone Problem still exists Sep 23, 2007 Prasad Burra Open
Bug CAL-185 Major Illegal instant due to time zone offset transition: 2007-11-04T02:00:00.000 Oct 30, 2007 Nicholas Ilacqua Closed
Improvement CAL-201 Major Replace any <h1>, <h2> etc markup with <div> so that they don't conflict with the {toc} macro. Nov 08, 2007 David Peterson Closed
Bug CAL-194 Major TAB character(s) in .ics file cause parsing of file to break. Oct 14, 2007 Jeffrey Silverman Resolved
Bug CAL-170 Major Calendar throws java.util.MissingResourceException: Can't find resource for bundle java.util.PropertyResourceBundle, key duration.allDay Oct 15, 2007 Dustin Pearce Resolved
Bug CAL-157 Major Exception when trying to edit calendar settings Oct 15, 2007 Bernd Rinn Resolved
Improvement CAL-186 Major Enable event summary to be linked in calendar-events Oct 19, 2007 David Peterson Resolved
Bug CAL-139 Major Forward and back buttons don't work consistently Oct 21, 2007 Tom Davies Resolved
Improvement CAL-69 Major Separate display of events for each calendar Oct 21, 2007 Susan Tran Resolved
Bug CAL-152 Critical $fullContextPath does not calculate correctly when subscribing to local calendar Nov 21, 2007 Ellen Daleng Resolved
Bug CAL-166 Critical getCalendar hangs, stopping Database Connection return Mar 27, 2008 Don Willis Resolved
Bug CAL-133 Critical server load when subscribed to iCals Nov 04, 2007 Jason Willis Reopened