TimeCalcPlugin < Extensions

You are here: Foswiki>Extensions Web>TimeCalcPlugin (24 Jan 2011, KennethLavrsen) (raw view)
<!--
This topic is part of the documentation for TimeCalcPlugin and is
automatically generated from Subversion. You can edit it, but if you do,
please make sure the maintainer of the extension knows about your changes,
otherwise your edits might be lost the next time the topic is uploaded.

If you want to report an error in the topic, please raise a report at
http://foswiki.org/Tasks/TimeCalcPlugin
-->
---+!! Time Calc Plugin

Perform calculations on time and dates

%TOC%

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

%INCLUDE{"VarWORKINGDAYS"}%

%INCLUDE{"VarADDWORKINGDAYS"}%

%INCLUDE{"VarTIMESHOWSTORE"}%

---++ 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 | %GMTIME{"$iso"}% |
| =$rcs= | RCS format timestamp | %GMTIME{"$rcs"}% |
| =$http= | E-mail & http format timestamp | %GMTIME{"$http"}% |
| =$epoch= | Number of seconds since 00:00 on 1st January, 1970 | %GMTIME{"$epoch"}% |

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="%<nop>HOLIDAYS%,%<nop>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

   * %<nop>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"}%

   * %<nop>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"}%

   * %<nop>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"}%
      
   * %<nop>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"}%
      
   * %<nop>TIMESHOWSTORE{"$day $month $year" time="$shipdate"}%
      * Returns (value if installed is 2011-01-05) %TIMESHOWSTORE{"$year-$mo-$day" time="$shipdate"}%
      
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 <br />(if installed)* | *Simulated result* |
| Start of project | %<nop>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 | %<nop>ADDWORKINGDAYS{date="$start" delta="30" store="developed"}% | %ADDWORKINGDAYS{date="$start" delta="30" store="developed"}% | 03 Mar 2011 |
| Build Part A | %<nop>ADDWORKINGDAYS{date="$developed" delta="8" store="part1"}% | %ADDWORKINGDAYS{date="$developed" delta="8" store="part1"}% | 15 Mar 2011 |
| Build Part B | %<nop>ADDWORKINGDAYS{date="$developed" delta="10" store="part2"}% | %ADDWORKINGDAYS{date="$developed" delta="10" store="part2"}% | 17 Mar 2011 |
| Test Complete | %<nop>ADDWORKINGDAYS{date="$part1,$part2" delta="10" store="tested"}% | %ADDWORKINGDAYS{date="$part1,$part2" delta="10" store="tested"}% | 31 Mar 2011 |
| Ship Product | %<nop>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.

---++ 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: | &copy; 2010, Kenneth Lavrsen and Foswiki Contributors |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Release: | 1.4 |
|  Version: | 10594 (2011-01-24) |
|  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
|  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 |
|  Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Support: | http://foswiki.org/Support/%TOPIC% |
PackageForm edit

ExtensionClassification	Information structuring and Search, Interface and Visualisation
ExtensionType	PluginPackage
Compatibility	Foswiki 1.0 and 1.1
SupportUrl	TimeCalcPlugin
DevelopedInSVN	Yes
ModificationPolicy	CoordinateWithAuthor
Topic attachments
I	Attachment	Action	Size	Date	Who
md5	TimeCalcPlugin.md5	manage	0.2 K	24 Jan 2011 - 07:34	KennethLavrsen
sha1	TimeCalcPlugin.sha1	manage	0.2 K	24 Jan 2011 - 07:34	KennethLavrsen
tgz	TimeCalcPlugin.tgz	manage	9.8 K	24 Jan 2011 - 07:33	KennethLavrsen
zip	TimeCalcPlugin.zip	manage	13.4 K	24 Jan 2011 - 07:33	KennethLavrsen
EXT	TimeCalcPlugin_installer	manage	4.2 K	24 Jan 2011 - 07:34	KennethLavrsen
Topic revision: r4 - 24 Jan 2011, KennethLavrsen
Extensions
Quick Links

Tools

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement.