TimeSincePlugin < Extensions

You are here: Foswiki>Extensions Web>TimeSincePlugin (14 Jul 2012, MichaelDaum) (raw view)

<!--
This topic is part of the documentation for TimeSincePlugin and is
automatically generated from Subversion. Do not edit it! Your edits
will 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/view/Tasks/TimeSincePlugin
-->
<!--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
-->
---+!! %TOPIC%

This plugin is inspired by the <nop>WordPress <nop>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
[[http://binarybonsai.com/wordpress/time-since][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 <nop>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.

%TOC%

---++ Syntax Rules

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

Without arguments the time since the current topic has been created will be displayed.

| *Argument* | *Description* |
| =from="&lt;time-experssion>"= | the starting time point, if ommited the current time |
| =to="&lt;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="&lt;format-string>"= | to be displayed if the tim difference is null; \
   defaults to "about now" |
| =format="&lt;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="&lt;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 &lt;=&gt; months
   * weeks &lt;=&gt; days
   * hours &lt;=&gt; minutes

For a further explanation/excuse, read 
[[http://search.cpan.org/~drolsky/DateTime-0.4304/lib/DateTime.pm#How_Datetime_Math_is_Done][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) %BR%
     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) *|
| %<nop>TIMESINCE% | 2 years and 6 months | %TIMESINCE% | 
| %<nop>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"}% |
| %<nop>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"}% | 
| %<nop>TIMESINCE{from="1955/04/18" to="1979-03-14" units="3"}% | 23 years, 11 months, 6 days \
| %TIMESINCE{from="1955/04/18" to="1979-03-14" units="3"}% |


---++ 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
<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Display time difference in a human readable way
-->

|  Plugin Author: | Michael Daum |
|  Copyright &copy;: | 2005-2009, Michael Daum http://michaeldaumconsulting.com |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Release: | 3.00 |
|  Version: | 3647 (2009-04-23) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 |
|  Dependency: | $Foswiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | CPAN:DateTime |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  Plugin Home: | Foswiki:Extensions/%TOPIC% |
|  Support: | Foswiki:Support/%TOPIC% |

PackageForm edit

ExtensionClassification	Interface and Visualisation
ExtensionType	PluginPackage
Compatibility
ImageUrl
DemoUrl	http://demo.michaeldaumconsulting.com/System/TimeSincePlugin
SupportUrl	TimeSincePlugin
DevelopedInSVN	Yes
ModificationPolicy	CoordinateWithAuthor

Topic attachments
I	Attachment	Action	Size	Date	Who
md5	TimeSincePlugin.md5	manage	0.2 K	17 Nov 2009 - 17:28	MichaelDaum
sha1	TimeSincePlugin.sha1	manage	0.2 K	17 Nov 2009 - 17:28	MichaelDaum
tgz	TimeSincePlugin.tgz	manage	7.3 K	17 Nov 2009 - 17:28	MichaelDaum
zip	TimeSincePlugin.zip	manage	9.9 K	17 Nov 2009 - 17:28	MichaelDaum
EXT	TimeSincePlugin_installer	manage	4.1 K	17 Nov 2009 - 17:28	MichaelDaum

Topic revision: r7 - 14 Jul 2012, MichaelDaum

Extensions

Quick Links

Tools

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