TimeTablePlugin

The TimeTablePlugin handles the tag %TIMETABLE% and creates a weekly timetable. The timetable is rendered with HTML tables and should work with all modern web browsers.

It also handles the tag %TTCM% (TimeTable Compatibilty Mode). The compatibility mode allows the usage of all TWiki:Plugins.CalendarPlugin event types. The %TTCM% tag should be placed into the description field of an event and must contain a time range and optional colors in a comma seperated list (<time range>[[','<forground color>][','<background color>]]), e.g:
you type:

   * 22 May 2006 - %TTCM{"7:00-1:00pm,white,black"}% Meeting
   * 23 May 2006 - 24 May 2006 - %TTCM{"7am-4pm,yellow"}% Conference

you get:

• 22 May 2006 - 07:00am-01:00pm Meeting
• 23 May 2006 - 24 May 2006 - 07:00am-04:00pm Conference

The %TTTOPICSETUP% (TimeTable Topic Setup) tag allows you to define default foreground/background colors (eventfgcolor/eventbgcolor attributes) and a time zone (timezone attribute) for all events on a topic. Please use it only once on a topic.

Example: (png image):

Syntax Rules

Events are defined with bullets. Following event types are supported to define entries for the timetable:

Event Type	Syntax	Example(s)
Single	* DDD - HH:MM - HH:MM - description	* Mon - 09:00 - 11:00 - Meeting
	* DDD - HH:MM - HH:MM - description - background color	* Mon - 09:00 - 11:00 - Meeting - green
	* DDD - HH:MM - HH:MM - description - foreground color, background color	* Mon - 09:00 - 11:00 - Meeting - white,black
List	* DDD, DDD,... - HH:MM - HH:MM - description	* Mon,Tue - 08:00 - 8:15 - Breakfast
	* DDD, DDD,... - HH:MM - HH:MM - description - background color	* Mon,Tue - 08:00 - 8:15 - Breakfast - yellow
	* DDD, DDD,... - HH:MM - HH:MM - description - forground color, background color	* Mon,Tue - 08:00 - 8:15 - Breakfast - white,black
Interval	* DDD - DDD - HH:MM - HH:MM - description	* Mon - Fri - 12:15 - 13:00 - Lunch
	* DDD - DDD - HH:MM - HH:MM - description - background color	* Mon - Fri - 12:15 - 13:00 - Lunch - green
	* DDD - DDD - HH:MM - HH:MM - description - foreground color, background color	* Mon - Fri - 12:15 - 13:00 - Lunch - white,black
Duration	instead of an end time (HH:MM) in a time range of a single/list/interval event you can define an event duration in days (d), hours (h) and/or minutes (m), e.g. one day: 1d ; one day and two hours: 1:2d ; one day, two hours and 30 minutes: 1:2:30d ; two hours: 2h ; two yours and 30 minutes: 2:30h ; 30 minutes: 30m	* Mon - 10:00 - 2h - every Monday 2 hours at 10 o'clock

If you enable the compatibility mode (see Attributes or Plugins Settings sections) you can also use all TWiki:Plugins.CalendarPlugin event types. Examples:

%TIMETABLE{compatmode="1" startdate="12 Jun 2006"}%
   * 12 Jun - %TTCM{"10am-5pm,yellow"}% Every 12th of June between 10am and 5pm
   * E Wed - Every Wednesday (whole-time)
   * 12 Jun 2006 - 19 Jun 2006 - %TTCM{"12:15pm-1pm,white,black"}% Lunch with Mary
   * 13 Jun 2006 - 10:00-12:00 Meeting 
   * 14 Jun 2006 - Meeting - 01pm-03pm,green

Notes:

• The parameter of the %TTCM% tag must not contain any whitespaces.
• Time ranges in a description field must not contain any whitespaces.
• If no %TTCM% tag or no time range was specified in a description of a TWiki:Plugins.CalendarPlugin event the event gets a full-time event (12:01am-11:59pm o'clock, 0-24h).

Attributes

Usage: %TIMETABLE{attribute1="value1" attribute2="value2" ...}%

Example: %TIMETABLE{lang="Deutsch" timeinterval="15" }%

Attribute	Comment	Default/Example
Behavior:
compatmode	if set to "1" all TWiki:Plugins.CalendarPlugin event types are supported (related: compatibility mode attributes); the description field can contain a time range (without any whitespaces, e.g. 1pm-2pm) or a %TTCM%-Tag (e.g. %TTCM{"7:00-1:00pm,white,black"}% ) with a time range and optional foreground and background color and without any whitespaces	compatmode="0"
days	days to show	days="7"
endtime	a end time, e.g. 18:00, 6:00pm, ...	endtime="8:00pm"
lang	Language used for weekdays in the table header and for event entries (e.g: English, Deutsch, Français, Español, Nederlands, Dansk, suomi, ...)	lang="English"
showweekend	show weekend if set to '1'	showweekend="1"
starttime	a start time, e.g. 7:00, 8a.m., 9:15a.m. ...	starttime="7:00am"
timeformat	time format; allowed values: 12, 12am, 12p.m., 12a.m, 12p.m. and 24	timeformat="24"
timeinterval	interval steps in minutes for the timeline	timeinterval="30"
timezone	a hour offset (allowed values: -12 ... 0 ... +12) for time correction or a time zone abbreviation (e.g. UTC, CET ...)	timezone="0"
timezoneabbr	a comma separated list of time zone abbreviations with UTC offsets; the standard time zone abbreviations will be extended with this user defined abbreviations	timezoneabbr="CET:+1, MEST:+2"
topic	a comma separated list of source topics; you can add a time zone to any source topic name by adding a ':' and a hour offset (-12 ... +12) or a time zone abbreviation, e.g: topic="MySourceTopic:-2" this time zone feature overwrites the timezone attribute of a %TTTOPICSETUP% tag	topic="%TOPIC%"
wholetimerow	enables/disables a whole-time event row (related attributes: wholetimerowtext, wholetimerowtitle)	wholetimerow="0"
workingendtime	working hours end time	workingendtime="5:00pm"
workingstarttime	working hours start time	workingstarttime="9:00am"
Compatibility Mode:
cmheaderformat	table header format of a day; a subset of strftime conversion specifiers is supported (only date not time specificiers; see manual page or TWiki:Codev.ConvergeDateTimeFormattingModels)	cmheaderformat="<font title=\"%A - %d %b %Y\" size=\"-2\">%b<br/>%a<br/>%e</font>"
daynames	costum daynames (a list separated by a 'Š' and starting on Monday; overwrites lang attribute)	daynames="MŠTŠWŠTŠFŠSŠS"
forcestartdate	if set to 1 the timetable starts with the given startdate ('0' means: the timetable view starts with Monday')	forcestartdate="0"
month	set a month (e.g. Jan, Feb ... or 01, 02, ... 12 ) or a month offset (e.g. +0, +1, -2,...)	month="+1"
monthnames	custom month names (a list separated by 'Š' and starting on January; overwrites lang attribute)	monthnames="JŠFŠMŠAŠMŠJŠJŠAŠSŠOŠNŠD"
navnext	navigation button to the next n days	navnext="&gt;&gt;"
navnexttitle	title text (tooltip text) for the navigation button to the next n days	navnexttitle="Next %n day(s)"
navprev	navigation button to the previous n days	navprev="&lt;&lt;"
navprevtitle	title text (tooltip text) for the navigation button to the previous n days	navprevtitle="Previous %n day(s)"
startdate	a start date (e.g. '1 Oct 2005') or a day offset (e.g. '10', '+30' or '-30')	startdate="+0"
year	set a year (e.g. 2005, 2006 ...) or a year offset (e.g. +0, +1, -1, ...)	year="+0"
Table formatting:
descrlimit	per line character limit for the description	descrlimit="10"
displaytime	display time in the event description of the timetable	displaytime="0"
eventbgcolor	default background color of an event cell (you can overwrite this with an event entry)	eventbgcolor = "#AAAAAA"
eventfgcolor	default text color of an event cell (you can overwrite this with an event entry)	eventfgcolor = "black"
headerformat	table header format of a day; a subset of strftime conversion specifiers is supported (only date not time specificiers; see manual page or TWiki:Codev.ConvergeDateTimeFormattingModels)	headerformat="<font title=\"%A - %d %b %Y\" size=\"-2\">%a</font>"
name	header content of the first column	name = "&nbsp;"
nowbgcolor	highlight current time in the timeline with a background color	nowbgcolor="black"
nowfgcolor	highlight current time in the timeline with a forgeround color	nowfgcolor="white"
showtimeline	show timeline left, right, or on both sides	showtimeline="both"
tablebgcolor	table background color	tablebgcolor="white"
tablecaption	table caption shown above the timetable	tablecaption="Timetable"
tableheadercolor	color of the table header	tableheadercolor="%WEBBGCOLOR%"
todaybgcolor	highlight today column with a background color	todaybgcolor="black"
todayfgcolor	highlight today column with a foreground color	todayfgcolor="white"
weekendbgcolor	highlight weekends with a column background color	weekendbgcolor="%WEBBGCOLOR%"
weekendfgcolor	highlight weekends with a column foreground color	weekendfgcolor="black"
wholetimerowpos	whole-time event row position (default: top), allowed values: top, bottom, both	wholetimerowpos="top"
wholetimerowtext	text in the time line of the whole-time event row	wholetimerowtext="24h"
wholetimerowtitle	alternate text for the wholetimerowtext	wholetimerowtitle="whole-time events"
workingbgcolor	highlight working hours in the timeline with a background color	workingbgcolor="white"
workingfgcolor	highlight working hours in the timeline with a foreground color	workingfgcolor="black"

Hints:

• You can use TextFormattingRules for some attribute values: tablecaption, name, navnext, navprev, wholetimerowtext
• Every attribute of %TIMETABLE% can also be used as plugin setting. You only have to use capital letters.

Examples

Timetable

	Mo	Tu	We	Th	Fr	Sa	Su
07:00 07:30 08:00 08:30 09:00 09:30 10:00 10:30 11:00 11:30 12:00 12:30 13:00 13:30 14:00 14:30 15:00 15:30 16:00 16:30 17:00 17:30 18:00 18:30 19:00 19:30 20:00	MONTEST1 MONTEST2     MONTEST3         MONTEST4	MONTEST1 TUETEST1 TUETEST2 TUETEST3     TUETESTFO         TUETEST4	WEDTEST1         WEDTEST2         WEDTEST3         WEDTEST4	THUTEST1	FRITEST1                     FRITEST2	SATTEST1 SATTEST2                 SATTEST3	SUNTEST1                                     SUNTEST2	07:00 07:30 08:00 08:30 09:00 09:30 10:00 10:30 11:00 11:30 12:00 12:30 13:00 13:30 14:00 14:30 15:00 15:30 16:00 16:30 17:00 17:30 18:00 18:30 19:00 19:30 20:00

• Mon,Tue - 9 - 14 - MONTEST1 - green
• Mon - 9 - 11 - MONTEST2 - yellow
• Mon - 10 - 13 - MONTEST3 - white,black
• Mon - 12 - 15 - MONTEST4

• Tue - 9 - 9:30 - TUETEST1
• Tue - 9 - 10:00 - TUETEST2
• Tue - 10:00 - 11:00 - TUETESTFO
• Tue - 9 - 11:30 - TUETEST3
• Tue - 12 - 15 - TUETEST4

• Wed - 7 - 9 - WEDTEST1
• Wed - 9 - 11 - WEDTEST2
• Wed - 11 - 13 - WEDTEST3
• Wed - 13 - 17 - WEDTEST4

• Thu - 7 - 20:30 - THUTEST1

• Fri - 7 - 10 - FRITEST1
• Fri - 12 - 15 - FRITEST2

• Sat - 5 - 10 - SATTEST1 - white,blue
• Sat - 6 - 21 - SATTEST2 - yellow
• Sat - 11 - 22 - SATTEST3 - green

• Sun - 9:18 - 17:35 - SUNTEST1 - red
• Sun - 18:00 - 18:15 - SUNTEST2 - yellow

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Render a weekly timetable

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

• Time format (default: 24, allowed: 12, 12pm, 12am, 12a.m.,12p.m., 12PM, 12AM, or 24):
  • # Set TIMEFORMAT = 12

• Timetable start time (default: 7:00am):
  • # Set STARTTIME = 7am

• Timetable end time (default: 8:00pm):
  • # Set ENDTIME = 8pm

• Enable/Disable whole-time event row (default: disabled):
  • # Set WHOLETIMEROW = 1
  • # Set WHOLETIMEROWPOS = top
  • # Set WHOLETIMEROWTEXT = 24h
  • # Set WHOLETIMEROWTITLE = whole-time events

• Character limitation of a description in a table cell line (default: 10):
  • # Set DESCRLIMIT = 15

• Show timeline on the left, right or both sides (default: both):
  • # Set SHOWTIMELINE = left

• Language (default: English - see manual page of Date::Calc perl module, e.g: English, Deutsch, Français, Español, Nederlands, Dansk, suomi, ...):
  • # Set LANG = Deutsch

• Enable/Disable compatibility mode (default: off) to (dis)allow TWiki:Plugins.CalendarPlugin event types:
  • # Set COMPATMODE = 1

• Set unknown parameter message (default: %RED% Sorry, some parameters are unknown: %UNKNOWNPARAMSLIST% %ENDCOLOR% <br/> Allowed parameters are (see TWiki.TimeTablePlugin topic for more details): %KNOWNPARAMSLIST%)
  • # Set UNKNOWNPARAMSMSG = Following parameter(s) is/are unknown: %UNKNOWNPARAMSLIST%

Note: Every attribute of %TIMETABLE% can also be used as plugin setting. You only have to use capital letters.

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 TWiki server.

• Download the ZIP file from the Plugin web (see below)
• Unzip TimeTablePlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/TimeTablePlugin.txt	Plugin topic
  data/TWiki/TimeTablePlugin.txt,v	Plugin topic repository
  lib/TWiki/Plugins/TimeTablePlugin.pm	Plugin Perl module
  lib/TWiki/Plugins/TimeTablePlugin/TimeTable.pm	Plugin Perl library
  pub/TWiki/TimeTablePlugin/example.png	example image

• Configure the Plugin:
  • TWiki 4.0 and up: Run the configure script to enable the Plugin
  • Change the Plugin settings as needed
• Test if the installation was successful:
  • see Examples section

Plugin Info

Plugin Author:	TWiki:Main.DanielRohde
Copyright:	© 2006, TWiki:Main.DanielRohde
License:	GPL (GNU General Public License)
Plugin Version:	V1.009 (7 Aug 2006)
Change History:
V1.009 (7 Aug 2006)	TWiki:Main.DanielRohde: added duration feature; added time zone abbreviations; improved performance; fixed conflict rendering bug; fixed time zone bugs (whole-time event handling, topic include)
V1.008 (2 Aug 2006)	TWiki:Main.DanielRohde: added timezone feature requested by TWiki:Main.BenWatts; fixed major midday/midnight (12pm/12am) bug reported by TWiki:Main.BenWatts; fixed overlapping day bug; fixed periodic event bug; fixed minor bugs (stylesheet bug: annyoing JavaScript errors; empty event row)
V1.007 (23 Jun 2006)	TWiki:Main.DanielRohde: fixed major bug (wholetimerow: empty column)
V1.006 (23 Jun 2006)	TWiki:Main.DanielRohde: fixed major mod_perl bug (paging in compatmode); added whole-time row feature; fixed minor bugs (empty column color; cutted text)
V1.005 (8 Jun 2006)	TWiki:Main.DanielRohde: fixed typos (documentation); added new features (compatmode only): inline time range feature and navigation; minor improvements (table header, ...)
V1.004 (31 May 2006)	TWiki:Main.DanielRohde: fixed typos (documentation, timeformat); added new attributes (days, forcestartdate, nowfgcolor, nowbgcolor); fixed minor bug (periodic repeater); added new event type (list)
V1.003 (24 May 2006)	TWiki:Main.DanielRohde: added compatibility mode (TWiki:Plugins.CalendarPlugin event types); added documentation and new attributes; fixed bugs (bgcolor bug; conflict rendering; documentation; error logs; warnings);
V1.002 (22 May 2006):	TWiki:Main.DanielRohde: fixed major bugs (conflict handling, preferences); added documentation;
V1.001 (19 May 2006):	TWiki:Main.DanielRohde: fixed some major bugs (conflict entries, parameter handling, long descriptions); added documentation;
V1.000 (16 May 2006):	TWiki:Main.DanielRohde: Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.021
CPAN Dependencies:	CPAN:Date::Calc CPAN:POSIX
Other Dependencies:	none
Perl Version:	5.005
Benchmarks:	GoodStyle nn%, FormattedSearch nn%, TimeTablePlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/TimeTablePlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/TimeTablePluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/TimeTablePluginAppraisal

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

-- TWiki:Main.DanielRohde - 16 May 2006