Skip to topic | Skip to bottom
TWiki.CalendarPluginr1.7 - 13 Sep 2005 - 12:03 - BruceDawsontopic end

Start of topic | Skip to actions

Calendar Plugin (version 1.017)

The CalendarPlugin handles the tag %CALENDAR% that inserts a monthly calendar in the page. Multiple topics can be specified as the source of the events, and these can be in any web.

Moreover, the Calendar highlights dates corresponding to a list of Events.

NB. This Plugin does not, and has never, observed topic permissions.

Usage example

You type:You get:If correctly installed:
A list of Events is just a bullet list like this:
  • 2 Feb - Andrea's birthday
  • A 7 Mar 1966 - Nicoletta's birthday
  • 29 May 1996 - Maria Teresa is born!
  • 29 Sep 1998 - Davide is born!

%CALENDAR{month="2" year="2002" bgcolor="cyan"}% %CALENDAR{month="3" year="2002" showweekdayheaders="1"}%

February 2002
Andrea's birthday 
10  11  12  13  14  15  16 
17  18  19  20  21  22  23 
24  25  26  27  28     

March 2002
Sunday Monday Tuesday Wednesday Thursday Friday Saturday
Nicoletta's birthday (36) 
10  11  12  13  14  15  16 
17  18  19  20  21  22  23 
24  25  26  27  28  29  30 


You type you get
%CALENDAR% a monthly calendar for the current month/year, with events taken from the current topic
%CALENDAR{<attributes>}% is the full syntax

Attributes recognized

Attribute Meaning Default
year="yyyy" The year Current year
year="+yy" or "-yy" Relative year Current year
month="mm" The month Current month
month="+mm" or "-mm" relative month Current month
gmtoffset="+/-hh" Timezone expressed as number of hours offset from GMT Server timezone
topic="TopicName" Topic containing events The topic containing the tag
topic="Web.TopicName1, Web.TopicName2" Topics containig events The topics containing the tags
web="Webname" Web containing the event topic The current web
lang="language" Language: First few characters of "English", "Français", "Deutsch", "Español", "Português", "Nederlands", "Italiano", "Norsk", "Svenska", "Dansk", "suomi", "Magyar", "Polski "English"
daynames="Mon¦Tue¦..." Custom day names "Monday¦Tuesday¦Wednesday¦Thursday¦
header="..." Text at the top of the calendar; use $m for current month, $y for year Current month and year
weekstartsonmonday="1" or "0" Flag to start week on Monday "0" (Sunday)
showdatenumbers="0" Show day numbers 1...31 in date cells. Note that showdatenumbers=1 means that HTML::CalendarMonthSimple will add the date numbers to the cells. If showdatenumbers=0, then the plugin adds the date numbers. The result of this is that a calendar will always show the date numbers. "0"
showweekdayheaders="1" Show the weekday headers "0"
weekdayheadersbig="0" If enabled, show weekday headers in bold cell headings "1"
cellalignment="left" Horizontal cell alignment of day cells: "left", "center", "right", "justify", "char" "center"
vcellalignment="middle" Vertical cell alignment of day cells: "top", "middle", "bottom", "baseline" "top"
cellheight="n" Height in pixels of each cell in the calendar Minimum height needed
format="..." How to highlight a date See above
width="n" or "n%" Width of calendar table in pixels or percent Minimum width needed
border="n" Border width of calendar table "1"
nowrap="1" or "0" Prevent cell content from wrapping "0"
bgcolor="#nnnn" Default background color of all cells unless redefined by other color settings below (use an HTML color-code like "#000000" as defined in StandardColors) white
contentcolor="#nnnn" Default content color of all cells unless redefined black
headercolor="#nnnn" Background color of the Month+Year header The web bgcolor
headercontentcolor="#nnnn" Content color of the Month+Year header contentcolor setting
weekdayheadercolor="#nnnn" Background color of weekdays' headers bgcolor setting
Content color of weekdays' headers contentcolor setting
weekendheadercolor="#nnnn" Background color of weekends' headers bgcolor setting
Content color of weekends' headers contentcolor setting
weekdaycolor="#nnnn" Background color of weekday cells bgcolor setting
weekdaycontentcolor="#nnnn" Content color of weekday cells contentcolor setting
weekendcolor="#nnnn" Background of weekend cells light gray
weekendcontentcolor="#nnnn" Content color of weekend cells contentcolor setting
todaycolor="#nnnn" Background of today's cell The web bgcolor
todaycontentcolor="#nnnn" Content color of today's cell contentcolor setting
and other attributes of HTML::CalendarMonthSimple

Event Syntax

Events are defined by bullets with the following syntax:

Event type Syntax Example
Single:    * dd MMM yyyy - description 09 Dec 2002 - Expo
Interval:    * dd MMM yyyy - dd MMM yyyy - description 02 Feb 2002 - 04 Feb 2002 - Vacation
Yearly:    * dd MMM - description 05 Jun - Every 5th of June
^    * w DDD MMM - description 2 Tue Mar - Every 2nd Tuesday of March
^    * L DDD MMM - description L Mon May - The last Monday of May
^    * A dd MMM yyyy - description A 20 Jul 1969 - First moon landing
This style will mark anniversaries of an event that occurred on the given date. The description will have " (x)" appended to it, where "x" indicates how many years since the occurence of the first date. The first date is not annotated.
Monthly:    * w DDD - description 1 Fri - Every 1st Friday of the month
^    * dd - description 14 - The 14th of every month
Weekly:    * E DDD - description E Wed - Every Wednesday
^    * E DDD dd MMM yyyy - description E Wed 27 Jan 2005 - Every Wednesday Starting 27 Jan 2005
^    * E DDD dd MMM yyyy - dd MMM yyyy - description E Wed 1 Jan 2005 - 27 Jan 2005 - Every Wednesday from 1 Jan 2005 through 27 Jan 2005 (inclusive)
Periodic:    * En dd MMM yyyy - description E3 02 Dec 2002 - Every three days starting 02 Dec 2002
^    * En dd MMM yyyy - dd MMM yyyy - description E3 12 Apr 2005 - 31 Dec 2005 - Every three days from 12 Apr 2005 through 31 Dec 2005 (inclusive)
Exception: Insert the following between the above syntax and the description:
X { dd MMM yyyy, dd MMM yyyy - dd MMM yyyy }
1 Fri X { 01 Dec 2002, 06 Dec 2002 - 14 Dec 2002 } - Every first Friday except on the 01 Dec 2002 and between 06 Dec 2002 and 14 Dec 2002

If an event falls in the selected month then the corresponding day is (by default):

  • highlighted (font size +2)
  • linked to the topic containing the event list
  • marked with an icon whose ALT string is the event's description
I.e. format is:
<a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/$web/$topic"><font size="+2">$old</font>
<img alt="$description" SRC="%PUBURLPATH%/$installWeb/CalendarPlugin/exclam.gif" /></a>

Default settings

  • One line description, shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = This plugin shows a monthly calendar with highlighted events
  • How the cell content is formatted
      * Set FORMAT = $old<br /><small>$description</small>
  • Note: You can add settings of any of the recognized attributes (in upper case like SHOWWEEKDAYHEADERS). Examples are shown below:
    • Set CELLALIGNMENT = center
    • Set VCELLALIGNMENT = center
    • Set WIDTH = 100%
    • Set GMTOFFSET = +4

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

  • Download the ZIP file from the Plugin web (see below)
  • The Plugin uses the HTML::CalendarMonthSimple and Date::Calc CPAN packages (see
    • Install Date::Calc
    • Install HTML::CalendarMonthSimple
    • To avoid an annoying log message, change line 272 of v1.25 by adding the section marked in RED :
      if ($self->year = = $todayyear && $self->month = = $todaymonth && defined $thisday && $thisday = = $todaydate)
      • For earlier or later versions where the line number may be different, search for todayyear. It currently (v1.22-v1.25) only appears twice: once to declare and set it, once to use it. On the line that uses it, add the && defined $thisday as shown above. -- TWiki:Main.AngusRogerson - 16 Aug 2004
  • Unzip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/CalendarPlugin.txt Plugin topic
    data/TWiki/CalendarPlugin.txt,v Plugin topic repository
    lib/TWiki/Plugins/ Plugin Perl module
    pub/TWiki/CalendarPlugin/exclam.gif Image file
  • Test if the installation was successful:
    • You should see two calendars near the Event list above

Plugin Info

Plugin Author: TWiki:Main/AndreaSterbini
Plugin Version: V1.017 (21 Jun 2005)
Change History:  
V1.017: TWiki:Main.DanielRohde: Added start and end date support for periodic repeaters; Added initlang patch by TWiki:Main.JensKloecker; Changed 'my' to 'local' so exceptions working again; Removed fetchxmap debug message; Fixed illegal date bug; Allowed month abbreviations in month attribute
V1.016: TWiki:Main/DavidBright: Added support for anniversary events; changed "our" to "my" in module to support perl versions prior to 5.6.0
V1.015: TWiki:Main.PatriceFournier: Added back support for preview showing unsaved events; Two loop fixes from TWiki:Main.DanielRohde
V1.014: TWiki:Main.NathanKerr: Added start and end date support for weekly repeaters
V1.013: TWiki:Main.MartinCleaver: Added multiple topic=web.topic parameters
V1.012: TWiki:Main/PeterThoeny: Added missing doc of gmtoffset parameter (was deleted in V1.011)
V1.011: TWiki:Main/PeterThoeny: Fixed deep recursion bug; preview shows now unsaved events; performance and resource improvements; documented most of HTML::CalendarMonthSimple attributes; TWiki:Main/PaulineCheung: Fixed uninitialized value in join
V1.010: TWiki:Main/DanBoitnott: Fixed variable conflict in timezone code
V1.009: TWiki:Main/DanBoitnott: Added ability to have event topics in other webs
V1.008: TWiki:Main/AnthonPang: Added daynames attribute; TWiki:Main/JensKloecker: Added lang attribute; TWiki:Main/DanBoitnott: Added yearly, monthly, weekly, and periodic events and exceptions
V1.006: TWiki:Main/DanBoitnott: Added monthly date support
V1.005: TWiki:Main/AkimDemaille: handle date intervals (thanks!)
V1.004: uses only HTML::CalendarMonthSimple, ISO dates, all possible settings, fixed month bug
V1.003: introducing HTML::CalendarMonthSimple
V1.002: TWiki:Main/ChristianSchultze: highlight today, relative month/year and debugging (thanks!)
V1.001: delayed load of used packages
V1.000: first release using only HTML::CalendarMonth
CPAN Dependencies: CPAN:HTML::CalendarMonthSimple >= v1.23, CPAN:Date::Calc
Other Dependencies: none
Perl Version: 5.000 and up
TWiki:Plugins/Benchmark: GoodStyle 95%, FormattedSearch 97%, CalendarPlugin 88% with installed Plugin
Plugin Home:

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main/AndreaSterbini - 27 Feb 2001
-- TWiki:Main/PeterThoeny - 15 Jan 2004
-- TWiki:Main.NathanKerr - 28 Jan 2005
-- TWiki:Main/DavidBright - 11 Mar 2005
-- TWiki:Main.DanielRohde - 21 Jun 2005

to top

I Attachment Action Size Date Who Comment
exclam.gif manage 0.1 K 02 Jan 2004 - 19:40 PeterThoeny Image of exclamation point

You are here: TWiki > CalendarPlugin

to top

All content is Copyright © 1999-2017 by, and the property of, the contributing authors.
Questions, comments, or concerns? Contact GNHLUG
Legal Notice (includes Terms of Service)