Calendar Plugin (version 1.020)

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. The calendar marks dates corresponding to the events.

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

Syntax Rules

Attributes recognized

Event Syntax

Events are defined by bullets with the following syntax:

Event formatting

For a table-style calendar, each day which has one or more events will have a list of the descriptions of those events. Each event description will be set in a small font. In other words, format is:

$old<br /><small>$description</small>

For a list-style calendar, if an event falls in the selected time period, then it is displayed (by default) as a bullet item with the date as dd Mmm yyyy In other words, datenumberformat is:

   * $day $mon $year

$old - $description

This displays the events in a form very similar to that in which they are specified (although specific to a particular date).

Multi-Day Event Formatting

The multidayformat option allows the description of each day of a multiday event to be displayed differently. This could be used to visually or textually annotate the description to indicate continuance from or to other days.

The option consists of a comma separated list of formats for each type of day in a multiday event:

first, middle, last, middle-unseen, last-unseen

Where:

• first is the format used when the first day of the event is displayed
• middle is the format used when the day being displayed is not the first or last day
• last is the format used when the last day of the event is displayed
• middle-unseen is the format used when the day being displayed is not the first or last day of the event, but the preceding days of the event have not been displayed. For example, if an event runs from 29 Apr to 2 May and a May calendar is being displayed, then this format would be used for 1 May.
• last-unseen is the format used when the day being displayed is the last day of the event, but the preceding days of the event have not been displayed. For example, if an event runs from 29 Apr to 1 May and a May calendar is being displayed, then this format would be used for 1 May. Note that in the previous example (event from 29 Apr to 2 May), this format would not be used for a May calendar because the event was "seen" on 1 May; so, the last format would be used for 2 May.

Within each format, date information for the current day can be substituted using the same format codes as accepted by %GMTIME%. An extension to these codes allows the date of the first and/or last day of the event to also be rendered.

• $first(format) will render the first date of the event according to format, where format is, again, a string of codes acceptable to %GMTIME%.
• $last(format) will render the last date of the event in the way just described for $first()

Missing formats will be filled in as follows:

• middle will be set to first
• last will be set to middle
• middle-unseen will be set to middle
• last-unseen will be set to last

Missing formats are different from empty formats. For example,

multidayformat="$description (until $last($day $month)),,"

specifies an empty format for middle and last. The result of this is that only the first day will be shown. Note that since an unspecified middle-unseen is set from the (empty) middle format, an event that begins prior to the calendar being displayed but ending in the current calendar will not be displayed. In contrast, multidayformat="$description" will simply display the description for each day of the event; all days (within the scope of the calendar) will be displayed.

The default format is to simply display the description of the event.

Examples

Plugin Settings

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Show a monthly calendar with highlighted events

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

• 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 = +10
  • #Set SHOWWEEKDAYHEADERS = 0
  • #Set WEEKSTARTSONMONDAY = 0

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 http://www.cpan.org)
  • Install Date::Calc
  • Install HTML::CalendarMonthSimple
  • To avoid an annoying log message, change line 272 of CalendarMonthSimple.pm v1.25 by adding the section marked in RED :
    

    if ($self->year = = $todayyear && $self->month = = $todaymonth %RED% && defined $thisday %ENDCOLOR% && $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 CalendarPlugin.zip 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/CalendarPlugin.pm	Plugin Perl module
  pub/TWiki/CalendarPlugin/exclam.gif	Image file

• (Dakar) Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.
• Test if the installation was successful:
  • You should see two calendars near the Event list above and a current month calendar below:

Plugin Info

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, 8 Feb 2006
-- TWiki:Main.DanielRohde - 21 Jun 2005