This plugin is inspired by the WordPress TimeSince plugin.
It which can be used to display a time difference in a human readable way, for instance to tell you that a topic has been published "2 days, 3 hours ago".
There are some problems with the original
TimeSince plugin for WordPress.
For example, it was only able to display a time diff with at most
two expressions: "1day, 2hours ago" or "1 week ago" but not "1 day, 2 hours and
3 minutes". It even displays only one time expression if the difference does
not occure in two adjacent time units (time units are year, month, week, day,
hour, minute). If a time interval differs in week and hour the TimeSince
WP plugin will only display the week difference and not the hours as week and
hour are not adjacent. This is fixed in the
TimeSincePlugin for Foswiki. Several
other parameters have been added to give a finer control of the format and the
information displayed.
Syntax Rules
%TIMESINCE%,
%TIMESINCE{[[from]="..."] [to="..."]}%
Without arguments the time since the current topic has been created will be displayed.
| Argument |
Description |
from="<time-experssion>" |
the starting time point, if ommited the current time |
to="<time-expression>" |
the ending timepoint, if ommited the current time |
units="1...7" |
number of time units to display, default 2; (example units="3": 2 months, 1 day and 3 minutes) |
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 |
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 |
Note, that switching off years and months (or any other two adjacent time unites) won't display the correct duration
when the times differ more than a year, that is: years can't be converted to weeks, the next lower unit.
The following units can be converted to each other:
- year <=> months
- weeks <=> days
- hours <=> minutes
For a further explanation/excuse, read
how datetime math is done.
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 |
3 years, 8 months |
| %TIMESINCE{"11 Sep 2001 - 8:45" units="7" seconds="on"}% |
4 years, 2 months, 2 days, 5 hours, 50 minutes, 16 seconds |
11 years, 8 months, 1 week, 3 days, 10 hours and 45 seconds |
| %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 |
topic was created 3 years, 8 months, 1 week, 6 days ago |
| %TIMESINCE{from="1955/04/18" to="1979-03-14" units="3"}% |
23 years, 11 months, 6 days |
23 years, 10 months, 3 weeks |
Plugin 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. 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
