Time Calc Plugin

Perform calculations on time and dates

Description

This plugin enables various calculations of time and dates that you will often need in a business environment.

Some of the features are

• Calculate working/business days between two dates
• Add/subtract a number of working/business days to/from a given list of dates
• When adding working dates the result is calculated based on the latest of the input dates. When subtracking the result is based on the earliest of the input dates.
• Display a time in any format
• Store and use special TimeCalcPlugin storage variables so a macro can use the result of an earlier used macro
• Chain project tasks and see the milestones with dates calculated based on the critical path through the project

Syntax Rules

WORKINGDAYS{...} -- calculate working days

• Calculates the number of business days between two dates
• Syntax: %WORKINGDAYS{startdate="date|$variable" enddate="date|$variable" holidays="comma separated list of dates" includestart="on|off" includeend="on|off"}%
• Supported parameters:

  Parameter:	Description:	Default:
  startdate="date"	date can be in any format defined in System/TimeSpecifications (time is ignorred), or it can be the name of a TimeCalcPlugin storage name prefixed by a '$'. E.g. $myvar	today
  enddate="date"	date can be in any format defined in System/TimeSpecifications (time is ignorred), or it can be the name of a TimeCalcPlugin storage name prefixed by a '$'. E.g. $myvar	today
  holidays="list of dates"	comma separated list of dates. The dates can be in any format defined in System/TimeSpecifications	None
  includestart="on or off"	Include the start date in the calculation	"off"
  includeend="on or off"	Include the end date in the calculation	"on"

• Example: %WORKINGDAYS{startdate="23 Nov 2010" enddate="10 Jan 2011" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011"}%
• This macro accepts TimeCalcPlugin storage variables as input dates but it cannot store any values because the result is not a date.

ADDWORKINGDAYS{...} -- add working days to date

• Calculates the day that is a number of working days later or earlier then a given date
• Syntax: %ADDWORKINGDAYS{"format" date="date|$variable" delta="days" holidays="comma separated list of dates"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "format"	Format of the displayed date. Time is always 12:00 in returned result. The tokens are specified Time Format Tokens below	format defined by the {DefaultDateFormat} setting in configure
  date="date"	List of dates separated by comma. If delta is a positive number the latest of the dates is used. If delta is negative the earliest date is used. The dates can be in any format defined in System/TimeSpecifications (time is ignorred), or it can be the name of a TimeCalcPlugin storage name prefixed by a '$'. E.g. $myvar	today
  delta="number of days"	Days can be positive for the future or negative for the past	0
  holidays="list of dates"	comma separated list of dates. The dates can be in any format defined in System/TimeSpecifications	none
  store="variablename"	Name of a variable in which the calculated date is stored. This variable can be used in another TimeCalcPlugin macro as an input date	none

• Example: %ADDWORKINGDAYS{"$year-$mo-$day date="23 Nov 2010" delta="25" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011"}%
• Note: When adding working days the start day is not included. The resulting enddate is included.

TIMESHOWSTORE{...} -- show formatted time and store it

• Displays a formatted date and time. The time is either given as a string or my a named TimeCalcPlugin storage variable. The resulting time can be stored in a storage variable.
• Syntax: %TIMESHOWSTORE{"format" time="time|$variable" store="name"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "format"	Format of the displayed date. The tokens are specified Time Format Tokens below	format defined by the {DefaultDateFormat} setting in configure
  time="time"	time can be in any format defined in System/TimeSpecifications (time is ignorred), or it can be the name of a TimeCalcPlugin storage name prefixed by a '$'. E.g. $myvar	time now
  delta="relative time"	The plugin accepts any relative time that the CPAN library Time::ParseDate can handle. E.g. "-3 months" , "last Monday", "+2 days", "next Wednesday", "2 weeks"	0
  store="variablename"	Name of a variable in which the calculated date is stored. This variable can be used in another TimeCalcPlugin macro as an input date	none

• Example: %TIMESHOWSTORE{"$year-$mo-$day date="23 Nov 2010" store="$myvar"}% displays 2010-11-23 and stored the date in myvar.

CALENDARDAYS{...} -- calculate calendar days

• Calculates the number of calendar days between two dates
• Syntax: %CALENDARDAYS{startdate="date|$variable" enddate="date|$variable" includestart="on|off" includeend="on|off"}%
• Supported parameters:

  Parameter:	Description:	Default:
  startdate="date"	date can be in any format defined in System/TimeSpecifications (time is ignorred), or it can be the name of a TimeCalcPlugin storage name prefixed by a '$'. E.g. $myvar	today
  enddate="date"	date can be in any format defined in System/TimeSpecifications (time is ignorred), or it can be the name of a TimeCalcPlugin storage name prefixed by a '$'. E.g. $myvar	today
  includestart="on or off"	Include the start date in the calculation	"off"
  includeend="on or off"	Include the end date in the calculation	"on"

• Example: %CALENDARDAYS{startdate="23 Nov 2010" enddate="10 Jan 2011"}%
• This macro accepts TimeCalcPlugin storage variables as input dates but it cannot store any values because the result is not a date.

Time Format Tokens

For macros where a time format can be specified the following tokens are used

Token:	Unit:	Example
$seconds	seconds	59
$minutes	minutes	59
$hours	hours	23
$day	day of month	31
$wday	day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat)	Thu
$dow	day of the week (Sun = 0)	2
$week	number of week in year (ISO 8601)	34
$month	short name of month	Dec
$mo	2 digit month	12
$year	4 digit year	1999
$ye	2 digit year	99
$tz	either "GMT" (if set to gmtime), or "Local" (if set to servertime)	GMT
$iso	ISO format timestamp	2024-04-19T17:51:42Z
$rcs	RCS format timestamp	2024/04/19 17:51:42
$http	E-mail & http format timestamp	Fri, 19 Apr 2024 17:51:42 GMT
$epoch	Number of seconds since 00:00 on 1st January, 1970	1713549102

Tokens can be shortened to 3 characters

Storage Macros

Most of the macros in this plugin can store variables that represents a time. These variables can be used later in another macro as an input.

Storage variables names can only be A-Z, a-z,0-9, and _.

A macro can only use a variable as input if it has been defined earlier in the topic. Macros are expanded from top to bottom, from left to right, from inside and out. If you try to use a variable that has not been defined, it is set to the current time.

Times that the result of adding working days are always stored as the date with time set to 12:00 GMT. Times given as inputs for the working day macros are converted to the same day at 12:00 GMT. Holidays are also converted to 12:00 GMT.

The storage feature can be used to create a chain of dates, for example a schedule in a table, where first date is defined using TIMESHOWSTORE, and the following dates are autocalculated by adding working days with ADDWORKINGDAYS

Holiday Lists

List of holidays has to given as comma separated dates. You cannot specify an interval. You can have duplicate dates. The duplicates are ignored. This means that you can define macros for public holidays of multiple countries, and a personal calendar with your vacation days and merge them even though they may contain duplicate dates.

You merge them like this: holidays="%HOLIDAYS%,%MYVACATIONDAYS%"

You can define a preference setting TIMECALCPLUGIN_HOLIDAYS in the current topic, in WebPreferences, or %SITEPREFERENCES% which defines a default holiday list which is then used if you do not specify any holiday parameter in ADDWORKINGDAYS.

Examples

• %WORKINGDAYS{startdate="23 Nov 2010" enddate="05 Jan 2011" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011"}%
  • Returns (value if installed is 30) %WORKINGDAYS{startdate="23 Nov 2010" enddate="05 Jan 2011" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011"}%

• %ADDWORKINGDAYS{date="23 Nov 2010" delta="20" holidays="24 Dec 2010, 25 Dec 2010, 26 Dec 2010" store="build1date"}%
  • Returns (value if installed is 21 Dec 2010) %ADDWORKINGDAYS{date="23 Nov 2010" delta="20" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011" store="build1date"}%

• %ADDWORKINGDAYS{date="23 Nov 2010" delta="15" holidays="24 Dec 2010, 25 Dec 2010, 26 Dec 2010" store="build2date"}%
  • Returns (value if installed is 14 Dec 2010) %ADDWORKINGDAYS{date="23 Nov 2010" delta="15" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011" store="build2date"}%

• %ADDWORKINGDAYS{date="$build1date,$build2date" delta="10" holidays="24 Dec 2010, 25 Dec 2010, 26 Dec 2010" store="shipdate"}%
  • Returns (value if installed is 05 Jan 2011) %ADDWORKINGDAYS{date="$build1date,$build2date" delta="10" holidays="24 Dec 2010, 25 Dec 2010, 01 Jan 2011" store="shipdate"}%

• %TIMESHOWSTORE{"$day $month $year" time="$shipdate"}%
  • Returns (value if installed is 2011-01-05) %TIMESHOWSTORE{"$year-$mo-$day" time="$shipdate"}%

• %TIMESHOWSTORE{time="12 Jun 2015" delta="last Sunday"}%
  • Returns (value if installed is 08 Jun 2015) %TIMESHOWSTORE{time="12 Jun 2015" delta="last Monday"}%

• %CALENDARDAYS{startdate="23 Nov 2010" enddate="10 Jan 2011"}%
  • Returns (value if installed is 48) %CALENDARDAYS{startdate="23 Nov 2010" enddate="10 Jan 2011"}%

Example of project plan. The test cannot be started until both part A and part B of the product have been built. The plugin calculates the date for Test Complete based on the critical path of the project.

Milestone	Raw macro	Actual result (if installed)	Simulated result
Start of project	%TIMESHOWSTORE{"$day $month $year" time="20 Jan 2011" store="start"}%	%TIMESHOWSTORE{"$day $month $year" time="20 Jan 2011" store="start"}%	20 Jan 2011
Develop Project	%ADDWORKINGDAYS{date="$start" delta="30" store="developed"}%	%ADDWORKINGDAYS{date="$start" delta="30" store="developed"}%	03 Mar 2011
Build Part A	%ADDWORKINGDAYS{date="$developed" delta="8" store="part1"}%	%ADDWORKINGDAYS{date="$developed" delta="8" store="part1"}%	15 Mar 2011
Build Part B	%ADDWORKINGDAYS{date="$developed" delta="10" store="part2"}%	%ADDWORKINGDAYS{date="$developed" delta="10" store="part2"}%	17 Mar 2011
Test Complete	%ADDWORKINGDAYS{date="$part1,$part2" delta="10" store="tested"}%	%ADDWORKINGDAYS{date="$part1,$part2" delta="10" store="tested"}%	31 Mar 2011
Ship Product	%ADDWORKINGDAYS{date="$tested" delta="5" store="shipped"}%	%ADDWORKINGDAYS{date="$tested" delta="10" store="shipped"}%	14 Apr 2011

Configuration of Working Days

• Configure setting {TimeCalcPlugin}{WorkingDays}
• Preference setting TIMECALCPLUGIN_WORKINGDAYS

By default the working days are defined as Monday, Tuesday, Wednesday, Thursday, Friday.

You can change this default in configure by setting the {TimeCalcPlugin}{WorkingDays}.

You can redefine the working days by setting the preference TIMECALCPLUGIN_WORKINGDAYS.

It is set by listing the names of the weekdays in English separated by commas.

E.g. to define a work week with Friday and Saturday off define {TimeCalcPlugin}{WorkingDays} as Sunday, Monday, Tuesday, Wednesday, Thursday

For a 7 day work week simply list all 7 days. Or use the CALENDARDAYS macro which does not use working days or holidays.

The plugin requires the CPAN library Time::ParseDate. Redhat/Centos users can run 'yum install perl-Time-ParseDate-2013' with the 'epel' repo enabled. Debian based distributions can install libtime-modules-perl

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Change History:
15 Jul 2015 (1.5)	Added CALENDARDAYS to the plugin. Extended the functionality of TIMESHOWSTORE to also accept relative dates as a delta parameter. Plugin now requires the CPAN module Time::ParseDate
24 Jan 2011 (1.4)	Document the store parameter for ADDWORKINGDAYS
05 Dec 2010 (1.3)	Add preference setting TIMECALCPLUGIN_HOLIDAYS so you do not have the specify the holidays in every single ADDWORKINGDAYS macro
26 Nov 2010 (1.2)	ADDWORKINGDAYS now accepts multiple input dates or variables and will calculates based on the date that defines the critical path of the project
25 Nov 2010 (1.1)	Adding configuration of working days of the week so it can be used in all cultures and all types of businesses
24 Nov 2010 (1.0)	Initial release with features WORKINGDAYS, ADDWORKINGDAYS, and TIMESHOWSTORE with storage variable functionality