Calendar Plugin (version 1.010)
[Development discussions in CalendarPluginDev?]
The
CalendarPlugin handles the new tag
%CALENDAR% that inserts a monthly calendar in the page.
Moreover, the Calendar highlights dates corresponding to a list of Events.
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
* 7 Mar - 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 |
| |
|
|
|
|
1 |
2
Andrea's birthday |
| 3 |
4 |
5 |
6 |
7 |
8 |
9 |
| 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 |
| |
|
|
|
|
1 |
2 |
| 3 |
4 |
5 |
6 |
7
Nicoletta's birthday |
8 |
9 |
| 10 |
11 |
12 |
13 |
14 |
15 |
16 |
| 17 |
18 |
19 |
20 |
21 |
22 |
23 |
| 24 |
25 |
26 |
27 |
28 |
29 |
30 |
| 31 |
|
|
|
|
|
|
|
|
%CALENDAR{month="2" year="2002" bgcolor="cyan"}%
%CALENDAR{month="3" year="2002" showweekdayheaders="1"}%
|
Syntax
| 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" ("+yy") | relative year | current year |
| month="mm" | the month | current month |
| month="+mm" ("-mm") | relative month | current month |
| bgcolor="color" | the bgcolor of the header | the web bgcolor |
| topic="TopicName" | topic containig events | the topic containing the tag |
| web="Webname" | web containing the event topic | the current web |
| lang="language" | language | "English" |
| daynames="headings" | custom day names | "Monday¦Tuesday¦Wednesday¦Thursday¦Friday¦Saturday¦Sunday" |
| format | how to highlight a date | see above |
| and all attributes of HTML::CalendarMonthSimple |
Available Languages
* English
* Français
* Deutsch
* Español
* Português
* Nederlands
* Italiano
* Norsk
* Svenska
* Dansk
* suomi
* Magyar
* Polski
Event Syntax
| | Syntax | Example |
|---|
| Normal Event | <3 spaces>* dd MMM yyyy - description | 09 Dec 2002 - Expo |
|---|
| Interval Event | <3 spaces>* dd MMM yyyy - dd MMM yyyy - description | 02 Feb 2002 - 04 Feb 2002 - Vacation |
|---|
| Yearly Event | <3 spaces>* dd MMM - description | 05 Jun - Every 5th of June |
|---|
| Yearly Event | <3 spaces>* [ w ¦ L] DDD MMM - description | 2 Tue Mar - Every 2nd Tuesday of March
L Mon May - The last Monday of May |
|---|
| Monthly Event | <3 spaces>* w DDD - description | 1 Fri - Every 1st Friday of the month |
|---|
| Monthly Event | <3 spaces>* dd - description | 14 - The 14th of every month |
|---|
| Weekly Event | <3 spaces>* E DDD - description | E Wed - Every Wednesday |
|---|
| Periodic Event | <3 spaces>* En dd MMM yyyy - description | E3 02 Dec 2002 - Every three days starting 02 Dec 2002 |
|---|
| Exception | 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> $description
Installation
The plugin uses the
HTML::CalendarMonthSimple and
Date::Calc CPAN packages (see
http://www.cpan.org).
* Install
Date::Calc
* Install
HTML::CalendarMonthSimple
* Unzip the
CalendarPlugin.zip package in your TWiki installation directory
* Change line 197 of CalendarMonthSimple.pm as follows to avoid an annoying log message.
if ($self->year == $todayyear && $self->month == $todaymonth && defined $thisday && $thisday == $todaydate)
If the installation is correct you should see two calendars near the Event list above.
Bugs
* because the CALENDAR tag is expanded after the INCLUDE tag, an included
%CALENDAR% tag will look for events in the INCLUDING topic. This can be avoided if the
topic="%TOPIC%" attribute is always explicitly used.
* During preview, a calendar with events in the same page shows events from the (old) saved page instead than from the current text
TODO
* Document all options and format parameters (see the code)
Changes
* V. 1.010:
DanBoitnott?: Fixed variable conflict in timezone code
* V. 1.009:
DanBoitnott?: Added ability to have event topics in other webs
* V. 1.008:
*
AnthonPang?: Added daynames attribute
*
JensKloecker?: Added lang attribute
*
DanBoitnott?: Added yearly, monthly, weekly, and periodic events and exceptions
* V. 1.006:
DanBoitnott?: Added monthly date support
* V. 1.005:
AkimDemaille?: handle date intervals (thanks!)
* V. 1.004: uses only HTML::CalendarMonthSimple, ISO dates, all possible settings, fixed month bug
* V. 1.003: introducing HTML::CalendarMonthSimple
* V. 1.002:
ChristianSchultze?: highlight today, relative month/year and debugging (thanks!)
* V. 1.001: delayed load of used packages
* V. 1.000: first release using only HTML::CalendarMonth
Plugin Info
--
AndreaSterbini? - 27 Feb 2001
Important Note:
As noted above, as of version V. 1.008 this plugin relies on an additional Perl module: Date::Calc. It is available on CPAN and should be installed on your system
before you upgrade this plugin. If you are running Mandrake simply install the perl-Date-Calc RPM package. This probably holds for Redhat as well.
--
DanBoitnott? - 09 May 2003
