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 date
  • 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

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

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 2014-12-19T03:15:00Z
$rcs RCS format timestamp 2014/12/19 03:15:00
$http E-mail & http format timestamp Fri, 19 Dec 2014 03:15:00 GMT
$epoch Number of seconds since 00:00 on 1st January, 1970 1418958900

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%"

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="builddate"}%
    • 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="builddate"}%

  • %ADDWORKINGDAYS{date="$builddate" delta="10" holidays="24 Dec 2010, 25 Dec 2010, 26 Dec 2010" store="shipdate"}%
    • Returns (value if installed is 05 Jan 2011) %ADDWORKINGDAYS{date="$builddate" 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"}%

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 Proto %ADDWORKINGDAYS{date="$developed" delta="10" store="proto"}% %ADDWORKINGDAYS{date="$developed" delta="10" store="proto"}% 17 Mar 2011
Test Complete %ADDWORKINGDAYS{date="$proto" delta="10" store="tested"}% %ADDWORKINGDAYS{date="$proto" 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

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

Plugin Author(s): Foswiki:Main.KennethLavrsen
Copyright: © 2010, Kenneth Lavrsen and Foswiki Contributors
License: GPL (GNU General Public License)
Release: 1.0
Version: 10057 (2010-11-24)
Change History:  
24 Nov 2010 (1.0) Initial release with features WORKINGDAYS, ADDWORKINGDAYS, and TIMESHOWSTORE with storage variable functionality
Home: http://foswiki.org/Extensions/TimeCalcPlugin
Support: http://foswiki.org/Support/TimeCalcPlugin

I Attachment Action Size Date Who Comment
TimeCalcPlugin.md5md5 TimeCalcPlugin.md5 manage 0.2 K 24 Nov 2010 - 21:02 KennethLavrsen  
TimeCalcPlugin.sha1sha1 TimeCalcPlugin.sha1 manage 0.2 K 24 Nov 2010 - 21:03 KennethLavrsen  
TimeCalcPlugin.tgztgz TimeCalcPlugin.tgz manage 8.4 K 24 Nov 2010 - 21:02 KennethLavrsen  
TimeCalcPlugin.zipzip TimeCalcPlugin.zip manage 11.4 K 24 Nov 2010 - 21:02 KennethLavrsen  
TimeCalcPlugin_installerEXT TimeCalcPlugin_installer manage 4.2 K 24 Nov 2010 - 21:02 KennethLavrsen  
Edit | Attach | Print version | History: r4 < r3 < r2 < r1 | Backlinks | View wiki text | Edit WikiText | More topic actions...
Topic revision: r1 - 24 Nov 2010, KennethLavrsen
 
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement. Creative Commons License