TimeSincePlugin

This plugin displays a duration between two points in time in a human readable way.

Syntax Rules

%TIMESINCE%, %TIMESINCE{[[from]="..."] [to="..."]}%

Argument	Description
topic="<topic-name>"	topic name to read the revision time from in case no from time was specified
web="<web-name>"	web name to read the revision time from in case no from time was specified
from="<time-experssion>"	the starting time point; defaults to last change time of topic
to="<time-expression>"	the ending timepoint; defaults to current time
units="1...7" or units="years,months,...,seconds"	number of time units to display (default 2) or list of units to be displayed; (example units="3", units="years, months, days")
seconds="on,off"	switch on/off seconds, default off
minutes="on,off"	switch on/off minutes
hours="on,off"	switch on/off hours
days="on,off"	switch on/off days
weeks="on,off"	switch on/off weeks
months="on,off"	switch on/off months
years="on,off"	switch on/off years
abs="on,off"	always return a positive difference between from and to
null="<format-string>"	to be displayed if the tim difference is null; defaults to "about now"
format="<format-string>"	format of the output, defaults to "$time", other usefull settings format="$time ago", format="replied $time later", "format="$time after the incident"
negformat="<format-string>"	use this format string if the time difference is negative

Time expressions can be specified in any of the following format:

• 31 Dec 2001 - 23:59 (Foswiki date)
• 31 Dec 2001
• 2001/12/31 23:59:59 (RCS date)
  also -, . instead of / in date, also . instead : in time
• 2001/12/31 23:59
• 2001/12/31
• 2001-12-31T23:59:59Z (ISO date)
• 2001-12-31T23:59:59+01:00
• 2001-12-31T23:59Z
• 2001-12-31T23:59+01:00
• epoch seconds

Format strings may contain the following:

• $time expands to the calculated time difference
• $percnt$ expands to a % char
• $dollar$ expands to a $ char
• $n expands to a linefeed
• $t expands to a tab space
• $nop expands to the empty string

Examples

You type	You get (simulated)	You get (if installed)
%TIMESINCE%	2 years and 6 months	%TIMESINCE%
%TIMESINCE{format="topic was created $time ago" null="topic has just now been saved" units="3" }%	topic was created 1 day, 3 hours and 8 minutes ago	%TIMESINCE{format="topic was created $time ago" null="topic has just now been saved" units="4"}%
%TIMESINCE{"11 Sep 2001 - 8:45" units="7" seconds="on"}%	4 years, 2 months, 2 days, 5 hours, 50 minutes, 16 seconds	%TIMESINCE{"11 Sep 2001 - 8:45" units="7" seconds="on"}%
%TIMESINCE{from="1955/04/18" to="1979-03-14" units="3"}%	23 years, 11 months, 1 day	%TIMESINCE{from="1955/04/18" to="1979-03-14" units="3"}%

Installation Instructions

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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

None

Change History

16 Aug 2018:	oo-ified core; fixed arithmetics
17 Nov 2014:	fixed duration math by removing dependency on CPAN::DateTime; improved units parameter
23 Apr 2009:	converted to Foswiki plugin
13 Aug 2008:	replaced CPAN:Time::Local with much more powerful and more precise CPAN:DateTime
03 Jan 2008:	improved parsing time formats
13 Oct 2006:	added negformat parameter
31 Aug 2006:	added NO_PREFS_IN_TOPIC
27 Apr 2006:	added lazy compilation
11 Nov 2005:	Initial version